devconfig-gen 1.0.0__py3-none-any.whl

devconfig_gen/providers/env_provider.py

@@ -0,0 +1,184 @@
+"""A second provider with real transformation: structured data -> ``.env``.
+
+Nested mappings are flattened into ``UPPER_SNAKE_CASE`` variables. This is a
+domain-neutral, non-JSON output format, which makes the provider contract's
+``media_type`` handling and multi-source merging easy to demonstrate.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping, Optional, Sequence, Tuple
+
+from ..models import (
+    Diagnostic,
+    GeneratedArtifact,
+    GenerationRequest,
+    GenerationResult,
+    ProviderField,
+    ProviderStep,
+)
+from ..validation import ValidationError, is_mapping
+
+_SEGMENT_RE = re.compile(r"[^A-Za-z0-9]+")
+
+DEFAULT_ARTIFACT_NAME = ".env"
+ENV_MEDIA_TYPE = "text/plain"
+
+
+class EnvProvider:
+    """Flatten a structured mapping into a ``.env`` document."""
+
+    name = "env"
+
+    steps: Sequence[ProviderStep] = (
+        ProviderStep(
+            id="variables",
+            title="Environment variables",
+            description="Nested keys are joined with '_' and upper-cased.",
+            i18n={"zh": {"title": "环境变量", "description": "嵌套键用 '_' 连接并转为大写。"}},
+            fields=(
+                ProviderField(
+                    "variables",
+                    type="mapping",
+                    required=True,
+                    title="Variables",
+                    description="Variables; nested keys become UPPER_SNAKE_CASE names.",
+                    i18n={"zh": {"title": "变量", "description": "变量；嵌套键会转为 UPPER_SNAKE_CASE 名称。"}},
+                ),
+            ),
+        ),
+    )
+
+    def describe_schema(self) -> Sequence[ProviderStep]:
+        return self.steps
+
+    def diagnose(self, request: GenerationRequest) -> Sequence[Diagnostic]:
+        _, diagnostics = self._prepare(request)
+        return tuple(diagnostics)
+
+    def validate(self, request: GenerationRequest):
+        return tuple(item.message for item in self.diagnose(request))
+
+    def generate(self, request: GenerationRequest) -> GenerationResult:
+        pairs, diagnostics = self._prepare(request)
+        if diagnostics:
+            raise ValidationError(diagnostics)
+        text = "\n".join(f"{key}={value}" for key, value in pairs.items()) + "\n"
+        name = request.options.get("name") or DEFAULT_ARTIFACT_NAME
+        return GenerationResult(
+            provider=self.name,
+            artifacts=(
+                GeneratedArtifact(
+                    name=str(name),
+                    content=text,
+                    media_type=ENV_MEDIA_TYPE,
+                ),
+            ),
+        )
+
+    # -- normalization + validation -----------------------------------------
+
+    def _prepare(self, request: GenerationRequest) -> Tuple[dict, list]:
+        diagnostics: list = []
+        context = request.context
+        if not is_mapping(context):
+            return {}, [Diagnostic("variables", "variables must be a mapping at the document root")]
+
+        raw: Mapping = context
+        if set(context.keys()) == {"variables"} and is_mapping(context["variables"]):
+            raw = context["variables"]
+
+        if not raw:
+            return {}, [Diagnostic("variables", "variables must not be empty")]
+
+        pairs: dict = {}
+        origins: dict = {}
+        self._flatten(raw, (), pairs, origins, diagnostics)
+        return pairs, diagnostics
+
+    def _flatten(
+        self,
+        source: Mapping,
+        prefix: Tuple[str, ...],
+        pairs: dict,
+        origins: dict,
+        diagnostics: list,
+    ) -> None:
+        for key, value in source.items():
+            segment = self._segment(key, prefix, diagnostics)
+            if segment is None:
+                continue
+            path = prefix + (segment,)
+
+            if is_mapping(value):
+                if not value:
+                    env_key = "_".join(path)
+                    self._assign(env_key, "", path, pairs, origins, diagnostics)
+                else:
+                    self._flatten(value, path, pairs, origins, diagnostics)
+            elif isinstance(value, (list, tuple)):
+                if any(is_mapping(item) for item in value):
+                    diagnostics.append(
+                        Diagnostic(
+                            ".".join(path).lower(),
+                            f"{'.'.join(path).lower()} must not contain mappings",
+                        )
+                    )
+                    continue
+                rendered = ",".join(self._scalar_to_env(item) for item in value)
+                self._assign("_".join(path), rendered, path, pairs, origins, diagnostics)
+            elif isinstance(value, (dict, set)):
+                diagnostics.append(
+                    Diagnostic(
+                        ".".join(path).lower(),
+                        f"{'.'.join(path).lower()} has an unsupported value type",
+                    )
+                )
+            else:
+                self._assign(
+                    "_".join(path), self._scalar_to_env(value), path, pairs, origins, diagnostics
+                )
+
+    def _assign(
+        self,
+        env_key: str,
+        value: str,
+        path: Tuple[str, ...],
+        pairs: dict,
+        origins: dict,
+        diagnostics: list,
+    ) -> None:
+        origin = ".".join(path).lower()
+        if env_key in pairs and origins.get(env_key) != origin:
+            diagnostics.append(
+                Diagnostic(
+                    origin,
+                    f"'{env_key}' collides with '{origins[env_key]}' after normalization",
+                )
+            )
+            return
+        pairs[env_key] = value
+        origins[env_key] = origin
+
+    @staticmethod
+    def _segment(key: Any, prefix: Tuple[str, ...], diagnostics: list) -> Optional[str]:
+        segment = _SEGMENT_RE.sub("_", str(key)).strip("_").upper()
+        path = ".".join(prefix + (str(key),)).lower()
+        if not segment:
+            label = path or "<root>"
+            diagnostics.append(Diagnostic(path, f"{label} is not a valid variable name"))
+            return None
+        return segment
+
+    @staticmethod
+    def _scalar_to_env(value: Any) -> str:
+        if value is None:
+            return ""
+        if value is True:
+            return "true"
+        if value is False:
+            return "false"
+        if isinstance(value, (int, float)):
+            return str(value)
+        return str(value)

devconfig_gen/providers/json_provider.py

@@ -0,0 +1,84 @@
+"""Pass-through JSON/YAML provider.
+
+This provider performs no field-level transformation; it exists so callers can
+normalize or re-serialize an arbitrary structured document through the same
+pipeline as richer providers.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .. import formats
+from ..models import (
+    GeneratedArtifact,
+    GenerationRequest,
+    GenerationResult,
+    ProviderField,
+    ProviderStep,
+)
+from ..validation import ValidationError
+
+
+class JsonProvider:
+    name = "json"
+
+    steps: Sequence[ProviderStep] = (
+        ProviderStep(
+            id="document",
+            title="Document",
+            description="Upload, paste, or edit an arbitrary JSON/YAML document to pass through unchanged.",
+            i18n={"zh": {"title": "文档", "description": "支持上传文件或直接粘贴/编辑任意 JSON/YAML 文档，原样透传与格式转换。"}},
+            fields=(
+                ProviderField(
+                    "document",
+                    type="document",
+                    required=True,
+                    title="Document Content",
+                    description="Upload a JSON/YAML file or paste/edit document content directly.",
+                    i18n={"zh": {"title": "文档内容", "description": "支持直接上传 JSON/YAML 文件，或直接粘贴/编辑文档内容。"}},
+                ),
+            ),
+        ),
+    )
+
+    def describe_schema(self) -> Sequence[ProviderStep]:
+        return self.steps
+
+    def _unwrap_context(self, context: Any) -> Any:
+        if (
+            isinstance(context, Mapping)
+            and set(context.keys()) == {"document"}
+            and isinstance(context["document"], Mapping)
+        ):
+            return context["document"]
+        return context
+
+    def validate(self, request: GenerationRequest):
+        context = self._unwrap_context(request.context)
+        if not isinstance(context, Mapping):
+            return ("document: expected a mapping at the root",)
+        return ()
+
+    def generate(self, request: GenerationRequest) -> GenerationResult:
+        errors = self.validate(request)
+        if errors:
+            raise ValidationError(errors)
+        fmt = formats.resolve_format(
+            request.options.get("format"),
+            name=request.options.get("name"),
+            default=formats.JSON,
+        )
+        suffix = "yaml" if fmt == formats.YAML else "json"
+        filename = request.options.get("name") or f"config.{suffix}"
+        context = self._unwrap_context(request.context)
+        return GenerationResult(
+            provider=self.name,
+            artifacts=(
+                GeneratedArtifact(
+                    name=str(filename),
+                    content=dict(context),
+                    media_type=formats.media_type_for(fmt),
+                ),
+            ),
+        )

devconfig_gen/registry.py

@@ -0,0 +1,38 @@
+"""Provider registration and lookup."""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable
+
+from .models import ConfigProvider
+from .providers import CustomProvider, EnvProvider, JsonProvider
+
+
+class ProviderRegistry:
+    def __init__(self, providers: Iterable[ConfigProvider] = ()):
+        self._providers: Dict[str, ConfigProvider] = {}
+        for provider in providers:
+            self.register(provider)
+
+    def register(self, provider: ConfigProvider) -> None:
+        name = str(provider.name).strip().lower()
+        if not name or name != provider.name:
+            raise ValueError("provider names must be non-empty lowercase strings")
+        if name in self._providers:
+            raise ValueError(f"provider already registered: {name}")
+        self._providers[name] = provider
+
+    def get(self, name: str) -> ConfigProvider:
+        try:
+            return self._providers[str(name).strip().lower()]
+        except KeyError as exc:
+            available = ", ".join(self.names()) or "none"
+            raise ValueError(f"unknown provider {name!r}; available: {available}") from exc
+
+    def names(self):
+        return tuple(sorted(self._providers))
+
+
+default_registry = ProviderRegistry(
+    (CustomProvider(), JsonProvider(), EnvProvider())
+)

devconfig_gen/validation.py

@@ -0,0 +1,148 @@
+"""Reusable, path-aware validation helpers.
+
+Providers use these primitives to collect every problem in one pass instead of
+failing on the first field. Each helper appends a :class:`Diagnostic` to the
+supplied list. The rendered message uses the leaf field name so it reads
+naturally, for example ``port must be between 1 and 65535, got 99999``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Sequence
+
+from .models import Diagnostic
+
+
+class ValidationError(ValueError):
+    """Raised when one or more validation errors are present."""
+
+    def __init__(self, diagnostics: Sequence[Any]):
+        self.diagnostics = tuple(_as_diagnostic(item) for item in diagnostics)
+        self.errors = tuple(item.message for item in self.diagnostics)
+        super().__init__("; ".join(self.errors))
+
+
+def _as_diagnostic(value: Any) -> Diagnostic:
+    if isinstance(value, Diagnostic):
+        return value
+    return Diagnostic(field="", message=str(value))
+
+
+def _leaf(path: str) -> str:
+    return path.rsplit(".", 1)[-1] if path else path
+
+
+def is_mapping(value: Any) -> bool:
+    return isinstance(value, Mapping)
+
+
+def is_integer(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def expect_mapping(value: Any, path: str, errors: list) -> Optional[Mapping]:
+    if not is_mapping(value):
+        errors.append(
+            Diagnostic(path, f"{_leaf(path)} must be a mapping, got {_describe(value)}")
+        )
+        return None
+    return value
+
+
+def expect_string(value: Any, path: str, errors: list, *, allow_empty: bool = False) -> Optional[str]:
+    leaf = _leaf(path)
+    if not isinstance(value, str):
+        errors.append(Diagnostic(path, f"{leaf} must be a string, got {_describe(value)}"))
+        return None
+    text = value.strip()
+    if not text and not allow_empty:
+        errors.append(Diagnostic(path, f"{leaf} must not be empty"))
+        return None
+    return text
+
+
+def expect_integer(
+    value: Any,
+    path: str,
+    errors: list,
+    *,
+    minimum: Optional[int] = None,
+    maximum: Optional[int] = None,
+) -> Optional[int]:
+    leaf = _leaf(path)
+    if not is_integer(value):
+        errors.append(Diagnostic(path, f"{leaf} must be an integer, got {_describe(value)}"))
+        return None
+    if minimum is not None and maximum is not None:
+        if value < minimum or value > maximum:
+            errors.append(
+                Diagnostic(path, f"{leaf} must be between {minimum} and {maximum}, got {value}")
+            )
+            return None
+    elif minimum is not None and value < minimum:
+        errors.append(Diagnostic(path, f"{leaf} must be >= {minimum}, got {value}"))
+        return None
+    elif maximum is not None and value > maximum:
+        errors.append(Diagnostic(path, f"{leaf} must be <= {maximum}, got {value}"))
+        return None
+    return value
+
+
+def expect_enum(
+    value: Any,
+    path: str,
+    errors: list,
+    *,
+    allowed: Sequence[str],
+    case_insensitive: bool = True,
+) -> Optional[str]:
+    leaf = _leaf(path)
+    options = ", ".join(str(option) for option in allowed)
+    if not isinstance(value, str):
+        errors.append(
+            Diagnostic(path, f"{leaf} must be one of {options}, got {_describe(value)}")
+        )
+        return None
+    candidate = value.strip()
+    if case_insensitive:
+        for option in allowed:
+            if candidate.lower() == option.lower():
+                return option
+    elif candidate in allowed:
+        return candidate
+    errors.append(Diagnostic(path, f"{leaf} must be one of {options}, got {value!r}"))
+    return None
+
+
+def expect_string_mapping(value: Any, path: str, errors: list) -> Optional[dict]:
+    if not is_mapping(value):
+        errors.append(
+            Diagnostic(path, f"{_leaf(path)} must be a mapping of labels, got {_describe(value)}")
+        )
+        return None
+    normalized = {}
+    for key, item in value.items():
+        key_text = str(key).strip()
+        if not key_text:
+            errors.append(Diagnostic(path, "label keys must not be empty"))
+            continue
+        if isinstance(item, (dict, list, tuple)):
+            errors.append(
+                Diagnostic(
+                    f"{path}.{key_text}",
+                    f"labels.{key_text} must be a scalar value, got {_describe(item)}",
+                )
+            )
+            continue
+        normalized[key_text] = "" if item is None else str(item)
+    return normalized
+
+
+def _describe(value: Any) -> str:
+    if isinstance(value, str):
+        return f"string {value!r}"
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return f"boolean {value}"
+    return f"{type(value).__name__} {value!r}"