pydantic-fixturegen 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

pydantic_fixturegen/cli/doctor.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from collections.abc import Iterable
+from dataclasses import dataclass, field
 from pathlib import Path
+from typing import Literal, cast
 
 import typer
 from pydantic import BaseModel
@@ -58,6 +60,13 @@ MEMORY_LIMIT_OPTION = typer.Option(
     help="Memory limit in megabytes for safe import subprocess.",
 )
 
+FAIL_ON_GAPS_OPTION = typer.Option(
+    None,
+    "--fail-on-gaps",
+    min=0,
+    help="Exit with code 2 when uncovered fields exceed this number (errors only).",
+)
+
 
 app = typer.Typer(invoke_without_command=True, subcommand_metavar="")
 
@@ -67,6 +76,43 @@ class ModelReport:
     model: type[BaseModel]
     coverage: tuple[int, int]
     issues: list[str]
+    gaps: list[FieldGap] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class GapInfo:
+    type_name: str
+    reason: str
+    remediation: str
+    severity: Literal["error", "warning"]
+
+
+@dataclass(slots=True)
+class FieldGap:
+    model: type[BaseModel]
+    field: str
+    info: GapInfo
+
+    @property
+    def qualified_field(self) -> str:
+        return f"{self.model.__name__}.{self.field}"
+
+
+@dataclass(slots=True)
+class TypeGapSummary:
+    type_name: str
+    reason: str
+    remediation: str
+    severity: Literal["error", "warning"]
+    occurrences: int
+    fields: list[str]
+
+
+@dataclass(slots=True)
+class GapSummary:
+    summaries: list[TypeGapSummary]
+    total_error_fields: int
+    total_warning_fields: int
 
 
 def doctor(  # noqa: D401 - Typer callback
@@ -79,10 +125,11 @@ def doctor(  # noqa: D401 - Typer callback
     timeout: float = TIMEOUT_OPTION,
     memory_limit_mb: int = MEMORY_LIMIT_OPTION,
     json_errors: bool = JSON_ERRORS_OPTION,
+    fail_on_gaps: int | None = FAIL_ON_GAPS_OPTION,
 ) -> None:
     _ = ctx  # unused
     try:
-        _execute_doctor(
+        gap_summary = _execute_doctor(
             target=path,
             include=include,
             exclude=exclude,
@@ -93,6 +140,10 @@ def doctor(  # noqa: D401 - Typer callback
         )
     except PFGError as exc:
         render_cli_error(exc, json_errors=json_errors)
+        return
+
+    if fail_on_gaps is not None and gap_summary.total_error_fields > fail_on_gaps:
+        raise typer.Exit(code=2)
 
 
 app.callback(invoke_without_command=True)(doctor)
@@ -117,7 +168,7 @@ def _execute_doctor(
     hybrid_mode: bool,
     timeout: float,
     memory_limit_mb: int,
-) -> None:
+) -> GapSummary:
     path = Path(target)
     if not path.exists():
         raise DiscoveryError(f"Target path '{target}' does not exist.", details={"path": target})
@@ -145,79 +196,167 @@ def _execute_doctor(
 
     if not discovery.models:
         typer.echo("No models discovered.")
-        return
+        empty_summary = GapSummary(summaries=[], total_error_fields=0, total_warning_fields=0)
+        return empty_summary
 
     registry = create_default_registry(load_plugins=True)
     builder = StrategyBuilder(registry, plugin_manager=get_plugin_manager())
 
     reports: list[ModelReport] = []
+    all_gaps: list[FieldGap] = []
     for model_info in discovery.models:
         try:
             model_cls = load_model_class(model_info)
         except RuntimeError as exc:
             raise DiscoveryError(str(exc)) from exc
-        reports.append(_analyse_model(model_cls, builder))
+        model_report = _analyse_model(model_cls, builder)
+        reports.append(model_report)
+        all_gaps.extend(model_report.gaps)
 
-    _render_report(reports)
+    gap_summary = _summarize_gaps(all_gaps)
+    _render_report(reports, gap_summary)
+    return gap_summary
 
 
 def _analyse_model(model: type[BaseModel], builder: StrategyBuilder) -> ModelReport:
     total_fields = 0
     covered_fields = 0
     issues: list[str] = []
-
-    try:
-        strategies = builder.build_model_strategies(model)
-    except ValueError as exc:  # missing provider
-        summaries = summarize_model_fields(model)
-        message = str(exc)
-        return ModelReport(
-            model=model,
-            coverage=(0, len(summaries)),
-            issues=[message],
-        )
+    field_gaps: list[FieldGap] = []
 
     summaries = summarize_model_fields(model)
 
-    for field_name, strategy in strategies.items():
+    for field_name, model_field in model.model_fields.items():
         total_fields += 1
         summary = summaries[field_name]
-        covered, field_issues = _strategy_status(summary, strategy)
+        try:
+            strategy = builder.build_field_strategy(
+                model,
+                field_name,
+                model_field.annotation,
+                summary,
+            )
+        except ValueError as exc:
+            message = str(exc)
+            issues.append(f"{model.__name__}.{field_name}: [error] {message}")
+            field_gaps.append(
+                FieldGap(
+                    model=model,
+                    field=field_name,
+                    info=GapInfo(
+                        type_name=summary.type,
+                        reason=message,
+                        remediation=(
+                            "Register a custom provider or configure an override for this field."
+                        ),
+                        severity="error",
+                    ),
+                )
+            )
+            continue
+
+        covered, gap_infos = _strategy_status(summary, strategy)
         if covered:
             covered_fields += 1
-        issues.extend(f"{model.__name__}.{field_name}: {msg}" for msg in field_issues)
-
-    return ModelReport(model=model, coverage=(covered_fields, total_fields), issues=issues)
+        for gap_info in gap_infos:
+            severity_label = "warning" if gap_info.severity == "warning" else "error"
+            issues.append(f"{model.__name__}.{field_name}: [{severity_label}] {gap_info.reason}")
+            field_gaps.append(FieldGap(model=model, field=field_name, info=gap_info))
+
+    return ModelReport(
+        model=model,
+        coverage=(covered_fields, total_fields),
+        issues=issues,
+        gaps=field_gaps,
+    )
 
 
-def _strategy_status(summary: FieldSummary, strategy: StrategyResult) -> tuple[bool, list[str]]:
+def _strategy_status(summary: FieldSummary, strategy: StrategyResult) -> tuple[bool, list[GapInfo]]:
     if isinstance(strategy, UnionStrategy):
-        issue_messages: list[str] = []
+        gap_infos: list[GapInfo] = []
         covered = True
         for choice in strategy.choices:
-            choice_ok, choice_issues = _strategy_status(choice.summary, choice)
+            choice_ok, choice_gaps = _strategy_status(choice.summary, choice)
             if not choice_ok:
                 covered = False
-                issue_messages.extend(choice_issues)
-        return covered, issue_messages
+            gap_infos.extend(choice_gaps)
+        return covered, gap_infos
 
-    messages: list[str] = []
+    gaps: list[GapInfo] = []
     if strategy.enum_values:
-        return True, messages
+        return True, gaps
 
     if summary.type in {"model", "dataclass"}:
-        return True, messages
+        return True, gaps
 
     if strategy.provider_ref is None:
-        messages.append(f"no provider for type '{summary.type}'")
-        return False, messages
+        gaps.append(
+            GapInfo(
+                type_name=summary.type,
+                reason=f"No provider registered for type '{summary.type}'.",
+                remediation="Register a custom provider or configure an override for this field.",
+                severity="error",
+            )
+        )
+        return False, gaps
 
     if summary.type == "any":
-        messages.append("falls back to generic type")
-    return True, messages
+        gaps.append(
+            GapInfo(
+                type_name="any",
+                reason="Falls back to generic `Any` provider.",
+                remediation="Define a provider for this shape or narrow the field annotation.",
+                severity="warning",
+            )
+        )
+    return True, gaps
+
 
+def _summarize_gaps(field_gaps: Iterable[FieldGap]) -> GapSummary:
+    grouped: dict[tuple[str, str, str, str], list[str]] = {}
+    error_fields = 0
+    warning_fields = 0
 
-def _render_report(reports: list[ModelReport]) -> None:
+    for gap in field_gaps:
+        key = (
+            gap.info.severity,
+            gap.info.type_name,
+            gap.info.reason,
+            gap.info.remediation,
+        )
+        grouped.setdefault(key, []).append(gap.qualified_field)
+        if gap.info.severity == "error":
+            error_fields += 1
+        else:
+            warning_fields += 1
+
+    summaries = [
+        TypeGapSummary(
+            type_name=type_name,
+            reason=reason,
+            remediation=remediation,
+            severity=cast(Literal["error", "warning"], severity),
+            occurrences=len(fields),
+            fields=sorted(fields),
+        )
+        for (severity, type_name, reason, remediation), fields in grouped.items()
+    ]
+    summaries.sort(
+        key=lambda item: (
+            0 if item.severity == "error" else 1,
+            item.type_name,
+            item.reason,
+        )
+    )
+
+    return GapSummary(
+        summaries=summaries,
+        total_error_fields=error_fields,
+        total_warning_fields=warning_fields,
+    )
+
+
+def _render_report(reports: list[ModelReport], gap_summary: GapSummary) -> None:
     for report in reports:
         covered, total = report.coverage
         coverage_pct = (covered / total * 100) if total else 100.0
@@ -231,5 +370,19 @@ def _render_report(reports: list[ModelReport]) -> None:
             typer.echo("  Issues: none")
         typer.echo("")
 
+    if not gap_summary.summaries:
+        typer.echo("Type coverage gaps: none")
+        return
+
+    typer.echo("Type coverage gaps:")
+    for summary in gap_summary.summaries:
+        level = "WARNING" if summary.severity == "warning" else "ERROR"
+        typer.echo(f"  - {summary.type_name}: {summary.reason} [{level}]")
+        typer.echo(f"    Fields ({summary.occurrences}):")
+        for field_name in summary.fields:
+            typer.echo(f"      • {field_name}")
+        typer.echo(f"    Remediation: {summary.remediation}")
+    typer.echo("")
+
 
 __all__ = ["app"]

pydantic_fixturegen/cli/gen/_common.py

@@ -6,10 +6,10 @@ import importlib
 import importlib.util
 import json
 import sys
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from pathlib import Path
 from types import ModuleType
-from typing import Literal
+from typing import Any, Literal
 
 import typer
 from pydantic import BaseModel
@@ -20,14 +20,17 @@ from pydantic_fixturegen.core.introspect import (
     IntrospectionResult,
     discover,
 )
+from pydantic_fixturegen.logging import Logger
 
 __all__ = [
     "JSON_ERRORS_OPTION",
+    "NOW_OPTION",
     "clear_module_cache",
     "discover_models",
     "load_model_class",
     "render_cli_error",
     "split_patterns",
+    "emit_constraint_summary",
 ]
 
 
@@ -40,6 +43,12 @@ JSON_ERRORS_OPTION = typer.Option(
     help="Emit structured JSON errors to stdout.",
 )
 
+NOW_OPTION = typer.Option(
+    None,
+    "--now",
+    help="Anchor timestamp (ISO 8601) used for temporal value generation.",
+)
+
 
 def clear_module_cache() -> None:
     """Clear cached module imports used during CLI execution."""
@@ -53,6 +62,49 @@ def split_patterns(raw: str | None) -> list[str]:
     return [part.strip() for part in raw.split(",") if part.strip()]
 
 
+def _package_hierarchy(module_path: Path) -> list[Path]:
+    hierarchy: list[Path] = []
+    current = module_path.parent.resolve()
+
+    while True:
+        init_file = current / "__init__.py"
+        if not init_file.exists():
+            break
+        hierarchy.append(current)
+        parent = current.parent.resolve()
+        if parent == current:
+            break
+        current = parent
+
+    hierarchy.reverse()
+    return hierarchy
+
+
+def _module_sys_path_entries(module_path: Path) -> list[str]:
+    resolved_path = module_path.resolve()
+    candidates: list[Path] = []
+    packages = _package_hierarchy(resolved_path)
+
+    if packages:
+        root_parent = packages[0].parent.resolve()
+        if root_parent != packages[0] and root_parent.is_dir():
+            candidates.append(root_parent)
+
+    parent_dir = resolved_path.parent
+    if parent_dir.is_dir():
+        candidates.append(parent_dir.resolve())
+
+    ordered: list[str] = []
+    seen: set[str] = set()
+    for entry in candidates:
+        entry_str = str(entry)
+        if entry_str in seen:
+            continue
+        ordered.append(entry_str)
+        seen.add(entry_str)
+    return ordered
+
+
 DiscoveryMethod = Literal["ast", "import", "hybrid"]
 
 
@@ -87,7 +139,7 @@ def load_model_class(model_info: IntrospectedModel) -> type[BaseModel]:
     return attr
 
 
-def render_cli_error(error: PFGError, *, json_errors: bool) -> None:
+def render_cli_error(error: PFGError, *, json_errors: bool, exit_app: bool = True) -> None:
     if json_errors:
         payload = {"error": error.to_payload()}
         typer.echo(json.dumps(payload, indent=2))
@@ -95,7 +147,81 @@ def render_cli_error(error: PFGError, *, json_errors: bool) -> None:
         typer.secho(f"{error.kind}: {error}", err=True, fg=typer.colors.RED)
         if error.hint:
             typer.secho(f"hint: {error.hint}", err=True, fg=typer.colors.YELLOW)
-    raise typer.Exit(code=int(error.code))
+    if exit_app:
+        raise typer.Exit(code=int(error.code))
+
+
+def emit_constraint_summary(
+    report: Mapping[str, Any] | None,
+    *,
+    logger: Logger,
+    json_mode: bool,
+    heading: str | None = None,
+) -> None:
+    if not report:
+        return
+
+    models = report.get("models")
+    if not models:
+        return
+
+    has_failures = any(
+        field.get("failures") for model_entry in models for field in model_entry.get("fields", [])
+    )
+
+    event_payload = {"report": report, "heading": heading}
+
+    if has_failures:
+        logger.warn(
+            "Constraint violations detected.",
+            event="constraint_report",
+            **event_payload,
+        )
+    else:
+        logger.debug(
+            "Constraint report recorded.",
+            event="constraint_report",
+            **event_payload,
+        )
+
+    if not has_failures or json_mode:
+        return
+
+    title = heading or "Constraint report"
+    typer.secho(title + ":", fg=typer.colors.CYAN)
+
+    for model_entry in models:
+        fields = [field for field in model_entry.get("fields", []) if field.get("failures")]
+        if not fields:
+            continue
+
+        typer.secho(
+            (
+                f"  {model_entry['model']} "
+                f"(attempts={model_entry['attempts']}, successes={model_entry['successes']})"
+            ),
+            fg=typer.colors.CYAN,
+        )
+        for field_entry in fields:
+            typer.secho(
+                (
+                    f"    {field_entry['name']} "
+                    f"(attempts={field_entry['attempts']}, successes={field_entry['successes']})"
+                ),
+                fg=typer.colors.YELLOW,
+            )
+            for failure in field_entry.get("failures", []):
+                location = failure.get("location") or [field_entry["name"]]
+                location_display = ".".join(str(part) for part in location)
+                typer.secho(
+                    f"      ✖ {location_display}: {failure.get('message', '')}",
+                    fg=typer.colors.RED,
+                )
+                if failure.get("value") is not None:
+                    typer.echo(f"        value={failure['value']}")
+                hint = failure.get("hint")
+                if hint:
+                    typer.secho(f"        hint: {hint}", fg=typer.colors.MAGENTA)
 
 
 def _load_module(module_name: str, locator: Path) -> ModuleType:
@@ -117,9 +243,10 @@ def _import_module_by_path(module_name: str, path: Path) -> ModuleType:
     if not path.exists():
         raise RuntimeError(f"Could not locate module source at {path}.")
 
-    sys_path_entry = str(path.parent.resolve())
-    if sys_path_entry not in sys.path:
-        sys.path.insert(0, sys_path_entry)
+    sys_path_entries = _module_sys_path_entries(path)
+    for entry in reversed(sys_path_entries):
+        if entry not in sys.path:
+            sys.path.insert(0, entry)
 
     unique_name = module_name
     if module_name in sys.modules: