dc-up 0.1.0__py3-none-any.whl

dc_up/fetch.py

@@ -0,0 +1,329 @@
+"""Template source access."""
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from typing import cast
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlparse
+from urllib.request import Request, urlopen
+
+from dc_up.errors import TemplateFetchError
+
+__all__ = [
+    "TemplateFile",
+    "TemplateSource",
+    "fetch_template_text",
+    "list_template_files",
+]
+
+
+@dataclass(frozen=True)
+class TemplateFile:
+    """One file discovered in a template layer."""
+
+    layer: str
+    template_path: str
+    target_path: str
+
+
+@dataclass(frozen=True)
+class TemplateSource:
+    """Canonical template source."""
+
+    repository: str = "denisecase/templates"
+    ref: str = "main"
+    local_path: Path | None = None
+
+
+def fetch_template_text(
+    *,
+    source: TemplateSource,
+    layer: str,
+    path: str,
+) -> str | None:
+    """Fetch one template file.
+
+    Args:
+        source: Template source.
+        layer: Template layer, such as ALL-PY.
+        path: Repository-relative managed file path.
+
+    Returns:
+        File text, or None if the template file does not exist.
+
+    Raises:
+        TemplateFetchError: If fetching fails for a reason other than not found.
+    """
+    if source.local_path is not None:
+        return _fetch_local_template_text(
+            local_path=source.local_path,
+            layer=layer,
+            path=path,
+        )
+
+    return _fetch_github_template_text(
+        repository=source.repository,
+        ref=source.ref,
+        layer=layer,
+        path=path,
+    )
+
+
+def list_template_files(
+    *,
+    source: TemplateSource,
+    layers: list[str],
+) -> list[TemplateFile]:
+    """List managed template files for selected layers.
+
+    Later layers override earlier layers by target path.
+    """
+    discovered: list[TemplateFile]
+
+    if source.local_path is not None:
+        discovered = _list_local_template_files(
+            local_path=source.local_path,
+            layers=layers,
+        )
+    else:
+        discovered = _list_github_template_files(
+            repository=source.repository,
+            ref=source.ref,
+            layers=layers,
+        )
+
+    by_target: dict[str, TemplateFile] = {}
+    for item in discovered:
+        by_target[item.target_path] = item
+
+    return list(by_target.values())
+
+
+def _list_github_template_files(
+    *,
+    repository: str,
+    ref: str,
+    layers: list[str],
+) -> list[TemplateFile]:
+    """List template files from GitHub's recursive tree API."""
+    encoded_ref = quote(ref, safe="")
+    url = (
+        f"https://api.github.com/repos/{repository}/git/trees/{encoded_ref}?recursive=1"
+    )
+
+    payload = _fetch_json_object(url)
+    tree = payload.get("tree")
+
+    if not isinstance(tree, list):
+        raise TemplateFetchError(f"Unexpected GitHub tree response: {url}")
+
+    selected_layers = set(layers)
+    layer_order = {layer: index for index, layer in enumerate(layers)}
+    items: list[TemplateFile] = []
+
+    tree_entries = cast(list[object], tree)
+    for entry in tree_entries:
+        if not isinstance(entry, dict):
+            continue
+
+        entry_data = cast(dict[object, object], entry)
+
+        if entry_data.get("type") != "blob":
+            continue
+
+        raw_path = entry_data.get("path")
+        if not isinstance(raw_path, str):
+            continue
+
+        layer, relative_path = _split_layer_path(raw_path)
+
+        if layer not in selected_layers:
+            continue
+
+        if _should_skip_template_path(relative_path):
+            continue
+
+        items.append(
+            TemplateFile(
+                layer=layer,
+                template_path=relative_path,
+                target_path=_target_path_for_template_path(relative_path),
+            )
+        )
+
+    return sorted(
+        items,
+        key=lambda item: (layer_order[item.layer], item.target_path),
+    )
+
+
+def _list_local_template_files(
+    *,
+    local_path: Path,
+    layers: list[str],
+) -> list[TemplateFile]:
+    """List template files from a local templates repository."""
+    root = local_path.expanduser().resolve()
+    items: list[TemplateFile] = []
+
+    for layer in layers:
+        layer_root = root / layer
+        if not layer_root.exists():
+            continue
+
+        for template_path in sorted(layer_root.rglob("*")):
+            if not template_path.is_file():
+                continue
+
+            relative_path = template_path.relative_to(layer_root).as_posix()
+            if _should_skip_template_path(relative_path):
+                continue
+
+            items.append(
+                TemplateFile(
+                    layer=layer,
+                    template_path=relative_path,
+                    target_path=_target_path_for_template_path(relative_path),
+                )
+            )
+
+    return items
+
+
+def _fetch_local_template_text(
+    *,
+    local_path: Path,
+    layer: str,
+    path: str,
+) -> str | None:
+    """Fetch template text from a local templates repository."""
+    template_path = local_path.expanduser().resolve() / layer / path
+
+    if not template_path.exists():
+        template_path_with_suffix = Path(f"{template_path}.template")
+        if not template_path_with_suffix.exists():
+            return None
+        template_path = template_path_with_suffix
+
+    if template_path.is_dir():
+        return None
+
+    try:
+        return template_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise TemplateFetchError(
+            f"Could not read template file: {template_path}"
+        ) from exc
+
+
+def _fetch_github_template_text(
+    *,
+    repository: str,
+    ref: str,
+    layer: str,
+    path: str,
+) -> str | None:
+    """Fetch template text from GitHub raw content."""
+    raw_path = f"{layer}/{path}"
+    url = f"https://raw.githubusercontent.com/{repository}/{ref}/{raw_path}"
+
+    text = _fetch_url_text(url)
+    if text is not None:
+        return text
+
+    template_url = f"{url}.template"
+    return _fetch_url_text(template_url)
+
+
+def _fetch_url_text(url: str) -> str | None:
+    """Fetch text from a trusted HTTPS URL, returning None for HTTP 404."""
+    parsed = urlparse(url)
+
+    if parsed.scheme != "https":
+        raise TemplateFetchError(f"Invalid URL scheme: {url}")
+
+    if parsed.netloc != "raw.githubusercontent.com":
+        raise TemplateFetchError(f"Invalid template host: {url}")
+
+    request = Request(  # noqa: S310
+        url,
+        headers={
+            "User-Agent": "dc-up",
+        },
+    )
+
+    try:
+        with urlopen(request, timeout=20) as response:  # noqa: S310
+            return response.read().decode("utf-8")
+    except HTTPError as exc:
+        if exc.code == 404:
+            return None
+        raise TemplateFetchError(f"Could not fetch template file: {url}") from exc
+    except URLError as exc:
+        raise TemplateFetchError(f"Could not fetch template file: {url}") from exc
+
+
+def _fetch_json_object(url: str) -> dict[str, object]:
+    """Fetch a trusted GitHub API JSON object."""
+    parsed = urlparse(url)
+
+    if parsed.scheme != "https":
+        raise TemplateFetchError(f"Invalid URL scheme: {url}")
+
+    if parsed.netloc != "api.github.com":
+        raise TemplateFetchError(f"Invalid template API host: {url}")
+
+    request = Request(  # noqa: S310
+        url,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "dc-up",
+        },
+    )
+
+    try:
+        with urlopen(request, timeout=20) as response:  # noqa: S310
+            payload = json.loads(response.read().decode("utf-8"))
+    except HTTPError as exc:
+        raise TemplateFetchError(f"Could not list template files: {url}") from exc
+    except URLError as exc:
+        raise TemplateFetchError(f"Could not list template files: {url}") from exc
+    except json.JSONDecodeError as exc:
+        raise TemplateFetchError(f"Could not parse template file list: {url}") from exc
+
+    if not isinstance(payload, dict):
+        raise TemplateFetchError(f"Unexpected GitHub API response: {url}")
+
+    return cast(dict[str, object], payload)
+
+
+def _split_layer_path(path: str) -> tuple[str, str]:
+    """Split a template repository path into layer and relative path."""
+    parts = path.split("/", 1)
+    if len(parts) != 2:
+        return path, ""
+
+    return parts[0], parts[1]
+
+
+def _target_path_for_template_path(path: str) -> str:
+    """Convert a template path to a target repository path."""
+    if path.endswith(".template"):
+        return path.removesuffix(".template")
+
+    return path
+
+
+def _should_skip_template_path(path: str) -> bool:
+    """Return whether a template path is internal or unsupported."""
+    if not path:
+        return True
+
+    if path.startswith((".dc-up/", "__pycache__/")):
+        return True
+
+    if Path(path).name == ".DS_Store":
+        return True
+
+    return path.endswith(".pyc")

dc_up/plan.py

@@ -0,0 +1,204 @@
+"""Build, print, and apply update plans."""
+
+from pathlib import Path
+
+from dc_up.errors import UnsafePathError
+from dc_up.fetch import (
+    TemplateFile,
+    TemplateSource,
+    fetch_template_text,
+    list_template_files,
+)
+from dc_up.render import render_template
+from dc_up.types import FileStatus, PlannedFile, RepositoryContext, UpdatePlan
+
+__all__ = [
+    "build_update_plan",
+    "print_update_plan",
+    "write_update_plan",
+]
+
+
+def build_update_plan(
+    *,
+    target: RepositoryContext,
+    source: TemplateSource,
+) -> UpdatePlan:
+    """Build an update plan from discovered template files."""
+    planned_files: list[PlannedFile] = []
+
+    template_files = list_template_files(
+        source=source,
+        layers=list(target.layers),
+    )
+
+    for template_file in template_files:
+        planned_files.append(
+            _plan_one_template_file(
+                target=target,
+                source=source,
+                template_file=template_file,
+            )
+        )
+
+    return UpdatePlan(
+        target=target,
+        files=tuple(planned_files),
+    )
+
+
+def print_update_plan(plan: UpdatePlan, *, write: bool) -> None:
+    """Print a human-readable update plan."""
+    mode = "WRITE" if write else "DRY RUN"
+
+    print(f"[dc-up] {mode}")  # noqa: T201
+    print(f"[dc-up] repo: {plan.target.repo_name}")  # noqa: T201
+    print(f"[dc-up] root: {plan.target.root}")  # noqa: T201
+    print(f"[dc-up] layers: {' -> '.join(plan.target.layers)}")  # noqa: T201
+    print("")  # noqa: T201
+
+    counts = _status_counts(plan)
+
+    print("[dc-up] managed files")  # noqa: T201
+    for file in plan.files:
+        status = _status_label(file.status, write=write)
+        source_label = f" [{file.source_layer}]" if file.source_layer else ""
+        print(f"{status:13} {file.path.as_posix()}{source_label}")  # noqa: T201
+
+    print("")  # noqa: T201
+    print(  # noqa: T201
+        "[dc-up] summary: "
+        f"{counts['current']} current, "
+        f"{counts['changed']} changed, "
+        f"{counts['missing']} missing, "
+        f"{counts['no-template']} no-template"
+    )
+
+    if not write:
+        print("")  # noqa: T201
+        print("[dc-up] no files written; rerun with --write to apply managed changes")  # noqa: T201
+
+
+def write_update_plan(plan: UpdatePlan) -> None:
+    """Write changed or missing managed files."""
+    for file in plan.files:
+        if file.status not in {"changed", "missing"}:
+            continue
+
+        if file.desired_text is None:
+            continue
+
+        target_path = _safe_target_path(plan.target.root, file.path)
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        target_path.write_text(file.desired_text, encoding="utf-8")
+
+
+def _plan_one_template_file(
+    *,
+    target: RepositoryContext,
+    source: TemplateSource,
+    template_file: TemplateFile,
+) -> PlannedFile:
+    """Plan one discovered template file."""
+    template_text = fetch_template_text(
+        source=source,
+        layer=template_file.layer,
+        path=template_file.target_path,
+    )
+
+    if template_text is None:
+        return PlannedFile(
+            path=Path(template_file.target_path),
+            status="no-template",
+            source_layer=template_file.layer,
+            source_path=f"{template_file.layer}/{template_file.template_path}",
+            current_text=_read_current_text(
+                target.root, Path(template_file.target_path)
+            ),
+            desired_text=None,
+        )
+
+    desired_text = render_template(template_text, target)
+    relative_path = Path(template_file.target_path)
+    current_text = _read_current_text(target.root, relative_path)
+
+    status = _file_status(
+        current_text=current_text,
+        desired_text=desired_text,
+    )
+
+    return PlannedFile(
+        path=relative_path,
+        status=status,
+        source_layer=template_file.layer,
+        source_path=f"{template_file.layer}/{template_file.template_path}",
+        current_text=current_text,
+        desired_text=desired_text,
+    )
+
+
+def _file_status(
+    *,
+    current_text: str | None,
+    desired_text: str,
+) -> FileStatus:
+    """Determine planned file status."""
+    if current_text is None:
+        return "missing"
+
+    if current_text == desired_text:
+        return "current"
+
+    return "changed"
+
+
+def _read_current_text(root: Path, path: Path) -> str | None:
+    """Read current file text if present."""
+    target_path = _safe_target_path(root, path)
+
+    if not target_path.exists() or target_path.is_dir():
+        return None
+
+    try:
+        return target_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def _safe_target_path(root: Path, path: Path) -> Path:
+    """Resolve a path under the repository root."""
+    target_path = (root / path).resolve()
+    root_resolved = root.resolve()
+
+    if target_path != root_resolved and root_resolved not in target_path.parents:
+        raise UnsafePathError(target_path)
+
+    return target_path
+
+
+def _status_counts(plan: UpdatePlan) -> dict[FileStatus, int]:
+    """Count file statuses."""
+    counts: dict[FileStatus, int] = {
+        "current": 0,
+        "changed": 0,
+        "missing": 0,
+        "no-template": 0,
+    }
+
+    for file in plan.files:
+        counts[file.status] += 1
+
+    return counts
+
+
+def _status_label(status: FileStatus, *, write: bool) -> str:
+    """Return display label for a file status."""
+    match status:
+        case "current":
+            return "CURRENT"
+        case "changed":
+            return "CHANGED" if write else "WOULD CHANGE"
+        case "missing":
+            return "ADDED" if write else "WOULD ADD"
+        case "no-template":
+            return "NO TEMPLATE"

dc_up/render.py

@@ -0,0 +1,35 @@
+"""Minimal template rendering."""
+
+from dc_up.types import RepositoryContext
+
+__all__ = ["render_template"]
+
+
+def render_template(text: str, target: RepositoryContext) -> str:
+    """Render simple repository identity tokens.
+
+    This is deliberately not a full template engine in v0.1.0.
+
+    Args:
+        text: Template text.
+        target: Target repository context.
+
+    Returns:
+        Rendered text.
+    """
+    replacements = {
+        "{{ repo_slug }}": target.repo_slug,
+        "{{repo_slug}}": target.repo_slug,
+        "{{ repo_name }}": target.repo_name,
+        "{{repo_name}}": target.repo_name,
+        "{{ repo_url }}": target.repo_url,
+        "{{repo_url}}": target.repo_url,
+        "{{ site_url }}": target.site_url,
+        "{{site_url}}": target.site_url,
+    }
+
+    rendered = text
+    for token, value in replacements.items():
+        rendered = rendered.replace(token, value)
+
+    return rendered

dc_up/todo.py

@@ -0,0 +1,97 @@
+"""Human action reporting for."""
+
+from dc_up.types import RepositoryContext, TodoReport
+
+__all__ = ["build_todo_report", "print_todo_report"]
+
+
+DEFAULT_REVIEW_PATHS: tuple[str, ...] = (
+    ".accountability/surfaces.toml",
+    "README.md",
+    "docs/project-instructions.md",
+    "docs/working-files.md",
+    "docs/success.md",
+    "docs/example-output.md",
+    "docs/index.md",
+    "src/**",
+    "tests/**",
+    "notebooks/**",
+    "sql/**",
+    "data/raw/**",
+)
+
+
+DEFAULT_CONFIRMATIONS: tuple[str, ...] = (
+    "repo-specific project description is accurate",
+    "dataset paths and expected outputs are correct",
+    "module-specific instructions still match the assignment",
+    "tests still match intended student or package behavior",
+    "notebook outputs are intentional, if notebooks are present",
+    "protected surfaces still reflect human review boundaries",
+)
+
+
+def build_todo_report(target: RepositoryContext) -> TodoReport:
+    """Build a repo-specific human review TODO report."""
+    review_paths = list(DEFAULT_REVIEW_PATHS)
+    confirmations = list(DEFAULT_CONFIRMATIONS)
+
+    if "pyproject.toml" in target.files:
+        review_paths.extend(
+            [
+                "pyproject.toml",
+                "uv.lock",
+            ]
+        )
+        confirmations.extend(
+            [
+                "package metadata is correct",
+                "dependency groups match current tooling expectations",
+            ]
+        )
+
+    if "package.json" in target.files:
+        review_paths.append("package.json")
+        confirmations.append("npm scripts and TypeScript tooling are current")
+
+    if any(path.startswith("notebooks/") for path in target.files):
+        confirmations.append("notebook execution state is intentional")
+
+    if any(path.startswith("sql/") for path in target.files):
+        confirmations.append("SQL examples and database paths are current")
+
+    return TodoReport(
+        target=target,
+        review_paths=tuple(_dedupe(review_paths)),
+        confirmations=tuple(_dedupe(confirmations)),
+    )
+
+
+def print_todo_report(report: TodoReport) -> None:
+    """Print a human review TODO report."""
+    print(f"PROJECT TODO: {report.target.repo_slug}")  # noqa: T201
+    print("")  # noqa: T201
+
+    print("Review repo-specific surfaces:")  # noqa: T201
+    for path in report.review_paths:
+        print(f"  {path}")  # noqa: T201
+
+    print("")  # noqa: T201
+    print("Confirm:")  # noqa: T201
+    for item in report.confirmations:
+        print(f"  {item}")  # noqa: T201
+
+
+def _dedupe(items: list[str]) -> list[str]:
+    """Deduplicate while preserving order."""
+    seen: set[str] = set()
+    result: list[str] = []
+
+    for item in items:
+        if item in seen:
+            continue
+
+        seen.add(item)
+        result.append(item)
+
+    return result