graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/scaffold/utils/merge3.py

@@ -0,0 +1,216 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Line-based three-way text merge (the diff3 algorithm) for config files.
+
+``scaffold enhance`` uses it on the config files a runtime, provider, target or
+CD change re-renders (``values-*.yaml``, ``.env.example``, Argo CD
+Applications): the template's own change (old snapshot -> new snapshot) is
+applied to the developer's copy when the two sets of edits touch different
+lines. Overlapping edits are never resolved automatically: ``merge3`` returns
+``None`` and the caller leaves the file alone and tells the developer.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import yaml
+
+
+def _sync_regions(
+    base: Sequence[str], ours: Sequence[str], theirs: Sequence[str]
+) -> list[tuple[int, int, int, int, int, int]]:
+    """Base ranges left unchanged by both sides, with their positions in each side.
+
+    Each tuple is ``(base_start, base_end, ours_start, ours_end, theirs_start,
+    theirs_end)``; the list ends with an empty sentinel region at the end of
+    every sequence.
+    """
+    ours_blocks = difflib.SequenceMatcher(None, base, ours, autojunk=False).get_matching_blocks()
+    theirs_blocks = difflib.SequenceMatcher(
+        None, base, theirs, autojunk=False
+    ).get_matching_blocks()
+    regions: list[tuple[int, int, int, int, int, int]] = []
+    i = j = 0
+    while i < len(ours_blocks) and j < len(theirs_blocks):
+        o_base, o_start, o_len = ours_blocks[i]
+        t_base, t_start, t_len = theirs_blocks[j]
+        start = max(o_base, t_base)
+        end = min(o_base + o_len, t_base + t_len)
+        if start < end:
+            o_sub = o_start + (start - o_base)
+            t_sub = t_start + (start - t_base)
+            regions.append((start, end, o_sub, o_sub + end - start, t_sub, t_sub + end - start))
+        if o_base + o_len < t_base + t_len:
+            i += 1
+        else:
+            j += 1
+    regions.append((len(base), len(base), len(ours), len(ours), len(theirs), len(theirs)))
+    return regions
+
+
+def merge3(base: Sequence[str], ours: Sequence[str], theirs: Sequence[str]) -> list[str] | None:
+    """Apply the base->theirs changes to ``ours``; ``None`` when the edits overlap.
+
+    Between two regions both sides left alone, a stretch changed on one side
+    only takes that side, a stretch changed identically on both takes either,
+    and a stretch changed differently on both is a conflict.
+    """
+    merged: list[str] = []
+    b = o = t = 0
+    for b_start, b_end, o_start, o_end, t_start, t_end in _sync_regions(base, ours, theirs):
+        base_chunk = list(base[b:b_start])
+        ours_chunk = list(ours[o:o_start])
+        theirs_chunk = list(theirs[t:t_start])
+        if ours_chunk == theirs_chunk:
+            merged.extend(ours_chunk)
+        elif ours_chunk == base_chunk:
+            merged.extend(theirs_chunk)
+        elif theirs_chunk == base_chunk:
+            merged.extend(ours_chunk)
+        else:
+            return None
+        merged.extend(base[b_start:b_end])
+        b, o, t = b_end, o_end, t_end
+    return merged
+
+
+def merge3_text(base: str, ours: str, theirs: str) -> str | None:
+    """:func:`merge3` over the lines of three texts (line endings kept as they are)."""
+    result = merge3(
+        base.splitlines(keepends=True),
+        ours.splitlines(keepends=True),
+        theirs.splitlines(keepends=True),
+    )
+    return None if result is None else "".join(result)
+
+
+class _Conflict(Exception):
+    """Both sides changed the same value differently."""
+
+
+_MISSING = object()
+
+
+def _merge_values(base: Any, ours: Any, theirs: Any) -> Any:
+    """Three-way merge of parsed documents (mappings merged key by key)."""
+    if ours == theirs:
+        return ours
+    if ours == base:
+        return theirs
+    if theirs == base:
+        return ours
+    if all(isinstance(v, dict) for v in (ours, theirs)) and isinstance(base, dict | type(None)):
+        base = base or {}
+        merged: dict[Any, Any] = {}
+        for key in [*ours, *(k for k in theirs if k not in ours)]:
+            value = _merge_values(
+                base.get(key, _MISSING), ours.get(key, _MISSING), theirs.get(key, _MISSING)
+            )
+            if value is not _MISSING:
+                merged[key] = value
+        return merged
+    raise _Conflict
+
+
+class _StrictLoader(yaml.SafeLoader):
+    """SafeLoader that refuses a repeated mapping key (a text merge can produce one)."""
+
+
+def _construct_mapping(loader: _StrictLoader, node: yaml.MappingNode, deep: bool = False) -> dict:
+    loader.flatten_mapping(node)
+    seen: set[Any] = set()
+    for key_node, _value in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        if key in seen:
+            raise yaml.constructor.ConstructorError(
+                None, None, f"repeated key {key!r}", key_node.start_mark
+            )
+        seen.add(key)
+    return yaml.SafeLoader.construct_mapping(loader, node, deep=deep)
+
+
+_StrictLoader.add_constructor(
+    yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
+    _construct_mapping,  # type: ignore[arg-type]
+)
+
+_ENV_ASSIGNMENT = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$")
+
+
+def _parse_env(text: str) -> dict[str, str]:
+    """The ``NAME=value`` assignments of an env file; a repeated name is an error."""
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        match = _ENV_ASSIGNMENT.match(line)
+        if not match:
+            continue
+        name, value = match.group(1), match.group(2).strip()
+        if name in values:
+            raise ValueError(f"repeated variable {name}")
+        values[name] = value
+    return values
+
+
+def _parse_for(path: str) -> Callable[[str], Any] | None:
+    name = path.rsplit("/", 1)[-1]
+    if name.endswith((".yaml", ".yml")):
+        return lambda text: yaml.load(text, Loader=_StrictLoader)
+    if name.startswith(".env"):
+        return _parse_env
+    return None
+
+
+def merge3_checked(base: str, ours: str, theirs: str, path: str) -> str | None:
+    """:func:`merge3_text` plus a check that the result means what both sides meant.
+
+    A line merge can succeed while producing something neither side wrote: two
+    insertions at almost the same place may land on either side of a shared
+    line (a ``redis:`` block added by the template next to one the developer
+    added gives two ``redis:`` keys). For YAML and env files the merged text is
+    parsed (repeated keys refused) and must equal a key-by-key three-way merge
+    of the three parsed documents; anything else is reported as a conflict.
+    """
+    merged = merge3_text(base, ours, theirs)
+    if merged is None:
+        return None
+    parse = _parse_for(path)
+    if parse is None:
+        return merged
+    try:
+        expected = _merge_values(parse(base), parse(ours), parse(theirs))
+        if parse(merged) != expected:
+            return None
+    except (_Conflict, ValueError, yaml.YAMLError):
+        return None
+    return merged
+
+
+def template_diff(old: str, new: str, path: str, *, limit: int = 40) -> str:
+    """The template's own change to ``path`` as a unified diff, for a manual merge."""
+    lines = list(
+        difflib.unified_diff(
+            old.splitlines(keepends=True),
+            new.splitlines(keepends=True),
+            fromfile=f"{path} (template before)",
+            tofile=f"{path} (template after)",
+        )
+    )
+    if len(lines) > limit:
+        lines = [*lines[:limit], f"... ({len(lines) - limit} more diff lines)\n"]
+    return "".join(line if line.endswith("\n") else line + "\n" for line in lines)

graph_agents_cli/scaffold/utils/openapi_seed.py

@@ -0,0 +1,199 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Carry the OpenAPI specs a seed ``--api-policy`` references into the new project.
+
+``lint`` resolves a relative ``openapi:`` path against the project root, while
+``create`` reads the seed policy next to the file the developer passed. Copying
+only ``api-policy.yaml`` would leave every ``openapi:`` reference dangling, and
+the first ``lint`` (the pr_checks gate) would fail on a project that was just
+created. So each referenced spec is copied too:
+
+* a relative path that stays inside the seed policy's directory keeps its path
+  (``specs/orders.yaml`` lands at ``<project>/specs/orders.yaml``);
+* anything else (an absolute path, ``..``, a hidden directory, or a path the
+  template already uses) is copied to ``openapi/<api name>/<file name>`` and the
+  ``openapi:`` value in the project's ``api-policy.yaml`` is rewritten in place,
+  keeping every comment and the rest of the file byte for byte.
+
+A reference that does not name a readable file is a configuration error
+(exit 3) raised before anything is rendered.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import pathlib
+import shutil
+from dataclasses import dataclass
+
+import yaml
+
+from graph_agents_cli._api_policy import POLICY_FILENAME, ApiPolicyFileError
+
+FALLBACK_DIR = "openapi"
+
+
+@dataclass(frozen=True)
+class SpecCopy:
+    """One ``openapi:`` reference of the seed policy and where it goes in the project."""
+
+    api: str
+    reference: str
+    source: pathlib.Path
+    # Project-relative POSIX path the reference keeps, or None when it cannot
+    # be kept (the spec then goes under openapi/<api>/ and the value is rewritten).
+    kept_path: str | None
+
+    @property
+    def fallback_path(self) -> str:
+        return f"{FALLBACK_DIR}/{self.api}/{self.source.name}"
+
+
+def plan_spec_copies(document: dict, policy_path: str | pathlib.Path) -> list[SpecCopy]:
+    """The specs to copy for ``document`` (read from ``policy_path``); exit 3 when one is missing."""
+    policy_file = pathlib.Path(policy_path)
+    policy_dir = policy_file.resolve().parent
+    copies: list[SpecCopy] = []
+    errors: list[str] = []
+    for name, api in (document.get("apis") or {}).items():
+        reference = api.get("openapi") if isinstance(api, dict) else None
+        if not reference:
+            continue
+        raw = pathlib.Path(str(reference).strip())
+        source = raw if raw.is_absolute() else policy_dir / raw
+        if not source.is_file():
+            errors.append(
+                f"apis.{name}.openapi: {reference} is not a readable file (a relative path "
+                f"is read next to {policy_file.name}); the new project needs a local copy "
+                "for `lint` to check calls against it"
+            )
+            continue
+        copies.append(
+            SpecCopy(
+                api=str(name),
+                reference=str(reference),
+                source=source.resolve(),
+                kept_path=_keepable(raw),
+            )
+        )
+    if errors:
+        raise ApiPolicyFileError(policy_file, errors)
+    return copies
+
+
+def _keepable(raw: pathlib.Path) -> str | None:
+    """The reference as a project path when it can stay as written, else None."""
+    if raw.is_absolute() or "\\" in str(raw):
+        return None
+    parts = raw.parts
+    if not parts or any(part in ("", ".", "..") or part.startswith(".") for part in parts):
+        return None
+    return pathlib.PurePosixPath(*parts).as_posix()
+
+
+def install_spec_copies(project_dir: pathlib.Path, copies: list[SpecCopy]) -> list[str]:
+    """Copy the planned specs into ``project_dir``; return one line per spec for the user.
+
+    Must run after the template is rendered and the seed policy copied to
+    ``api-policy.yaml``: a kept path the template already uses is not
+    overwritten, the fallback location is used instead.
+    """
+    lines: list[str] = []
+    policy_path = project_dir / POLICY_FILENAME
+    rewrites: dict[str, str] = {}
+    for copy in copies:
+        target = copy.kept_path
+        if target is None or _occupied(project_dir / target, copy.source):
+            target = copy.fallback_path
+            rewrites[copy.api] = target
+        destination = project_dir / target
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(copy.source, destination)
+        lines.append(f"{copy.api}: {copy.reference} -> {target}")
+    if rewrites and not _rewrite_openapi_values(policy_path, rewrites):
+        for api, target in rewrites.items():
+            lines.append(
+                f"{api}: could not rewrite openapi: in {POLICY_FILENAME}; set it to {target}"
+            )
+    return lines
+
+
+def _occupied(path: pathlib.Path, source: pathlib.Path) -> bool:
+    """True when ``path`` holds something other than a copy of ``source``."""
+    if not path.exists() and not path.is_symlink():
+        return False
+    try:
+        return not path.is_file() or path.read_bytes() != source.read_bytes()
+    except OSError:
+        return True
+
+
+def _rewrite_openapi_values(policy_path: pathlib.Path, rewrites: dict[str, str]) -> bool:
+    """Replace ``apis.<api>.openapi`` scalars in place; True when the result parses as intended.
+
+    The file is edited at the positions YAML reports for each value, so
+    comments and formatting survive. The result is re-read and compared: on
+    any mismatch (an alias shared by several APIs, say) the file is restored.
+    """
+    original = policy_path.read_text(encoding="utf-8")
+    try:
+        root = yaml.compose(original, Loader=yaml.SafeLoader)
+    except yaml.YAMLError as exc:
+        logging.warning("Could not parse %s to rewrite openapi paths: %s", policy_path, exc)
+        return False
+    spans: list[tuple[int, int, str]] = []
+    for api, target in rewrites.items():
+        node = _openapi_node(root, api)
+        if node is None or node.start_mark is None or node.end_mark is None:
+            return False
+        spans.append((node.start_mark.index, node.end_mark.index, json.dumps(target)))
+    text = original
+    for start, end, value in sorted(spans, reverse=True):
+        text = text[:start] + value + text[end:]
+    try:
+        parsed = yaml.safe_load(text)
+        ok = all(parsed["apis"][api]["openapi"] == target for api, target in rewrites.items())
+        ok = ok and _without_openapi(parsed) == _without_openapi(yaml.safe_load(original))
+    except (yaml.YAMLError, KeyError, TypeError):
+        ok = False
+    if not ok:
+        return False
+    policy_path.write_text(text, encoding="utf-8")
+    return True
+
+
+def _openapi_node(root: yaml.Node | None, api: str) -> yaml.ScalarNode | None:
+    apis = _mapping_value(root, "apis")
+    entry = _mapping_value(apis, api)
+    value = _mapping_value(entry, "openapi")
+    return value if isinstance(value, yaml.ScalarNode) else None
+
+
+def _mapping_value(node: yaml.Node | None, key: str) -> yaml.Node | None:
+    if not isinstance(node, yaml.MappingNode):
+        return None
+    for key_node, value_node in node.value:
+        if isinstance(key_node, yaml.ScalarNode) and key_node.value == key:
+            return value_node
+    return None
+
+
+def _without_openapi(document: dict) -> dict:
+    apis = {
+        name: {k: v for k, v in (api or {}).items() if k != "openapi"}
+        for name, api in (document.get("apis") or {}).items()
+    }
+    return {**document, "apis": apis}