dc-up 0.1.0__py3-none-any.whl

dc_up/__init__.py

@@ -0,0 +1 @@
+"""dc-up package."""

dc_up/__main__.py

@@ -0,0 +1,6 @@
+"""Run dc-up as a module."""
+
+from dc_up.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dc_up/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

dc_up/baseline.py

@@ -0,0 +1,155 @@
+"""Baseline layer inference and managed file declarations."""
+
+from pathlib import Path
+import tomllib
+from typing import cast
+
+__all__ = [
+    "PRESERVE_PATTERNS",
+    "infer_layers",
+]
+
+TomlTable = dict[str, object]
+
+COURSE_PREFIXES: tuple[str, ...] = (
+    "datafun-",
+    "streaming-",
+    "cintel-",
+    "nlp-",
+)
+
+
+PRESERVE_PATTERNS: tuple[str, ...] = (
+    "README.md",
+    "docs/**",
+    "src/**",
+    "tests/**",
+    "notebooks/**",
+    "data/**",
+    "sql/**",
+    "artifacts/**",
+)
+
+
+def infer_layers(
+    *,
+    repo_root: Path,
+    repo_slug: str,
+    files: set[str],
+) -> list[str]:
+    """Infer additive template layers for a repository."""
+    normalized_slug = repo_slug.lower()
+
+    if "package.json" in files and "pyproject.toml" not in files:
+        layers = ["ALL", "ALL-TS"]
+    elif "notebook" in normalized_slug or normalized_slug.endswith("-notebooks"):
+        layers = ["ALL", "ALL-PY", "ALL-PY-NB"]
+    elif "kafka" in normalized_slug:
+        layers = ["ALL", "ALL-PY", "ALL-PY-KAFKA"]
+    elif normalized_slug == "dc-up" or _looks_like_pypi_package(repo_root):
+        layers = ["ALL", "ALL-PY", "ALL-PY-SRC", "ALL-PY-PYPI"]
+    else:
+        layers = ["ALL", "ALL-PY", "ALL-PY-SRC"]
+
+    if _looks_like_course_repo(repo_slug=repo_slug, files=files):
+        layers.append("ALL-COURSE")
+
+    return layers
+
+
+def _has_console_scripts(project: TomlTable) -> bool:
+    """Return whether project metadata declares console scripts."""
+    scripts = _as_string_dict(project.get("scripts"))
+    if scripts:
+        return True
+
+    entry_points = _as_table(project.get("entry-points"))
+    console_scripts = _as_string_dict(entry_points.get("console_scripts"))
+
+    return bool(console_scripts)
+
+
+def _read_toml(path: Path) -> TomlTable:
+    """Read a TOML file as typed object data."""
+    with path.open("rb") as file:
+        return cast(TomlTable, tomllib.load(file))
+
+
+def _as_table(value: object) -> TomlTable:
+    """Return value as a TOML table or an empty table."""
+    if isinstance(value, dict):
+        return cast(TomlTable, value)
+    return {}
+
+
+def _as_string_list(value: object) -> list[str]:
+    """Return value as a list of strings."""
+    if not isinstance(value, list):
+        return []
+
+    return [str(item) for item in cast(list[object], value)]
+
+
+def _as_string_dict(value: object) -> dict[str, str]:
+    """Return value as a string-to-string dictionary."""
+    if not isinstance(value, dict):
+        return {}
+
+    table = cast(dict[object, object], value)
+    return {str(key): str(item) for key, item in table.items()}
+
+
+def _as_bool(value: object) -> bool:
+    """Return value as a boolean."""
+    if isinstance(value, bool):
+        return value
+    return False
+
+
+def _looks_like_course_repo(*, repo_slug: str, files: set[str]) -> bool:
+    """Return whether a repository looks like a course project repo."""
+    normalized_slug = repo_slug.lower()
+
+    if not normalized_slug.startswith(COURSE_PREFIXES):
+        return False
+
+    # Avoid admin/maintenance repos unless you decide they should get course docs.
+    if normalized_slug.endswith("-00-admin") or normalized_slug.endswith("-admin"):
+        return False
+
+    # Require project repo shape, not just matching name.
+    return "pyproject.toml" in files
+
+
+def _looks_like_pypi_package(repo_root: Path) -> bool:
+    """Return whether pyproject.toml looks like a publishable package.
+
+    This is intentionally stricter than "has pyproject + src" so ordinary
+    course repos do not accidentally receive PyPI release surfaces.
+    """
+    pyproject_path = repo_root / "pyproject.toml"
+    if not pyproject_path.exists():
+        return False
+
+    try:
+        data = _read_toml(pyproject_path)
+    except OSError:
+        return False
+    except tomllib.TOMLDecodeError:
+        return False
+
+    project = _as_table(data.get("project"))
+    if not project:
+        return False
+
+    if _has_console_scripts(project):
+        return True
+
+    classifiers = _as_string_list(project.get("classifiers"))
+    if any("PyPI" in item for item in classifiers):
+        return True
+
+    tool = _as_table(data.get("tool"))
+    uv = _as_table(tool.get("uv"))
+
+    return _as_bool(uv.get("package"))

dc_up/cli.py

@@ -0,0 +1,145 @@
+"""Command-line interface for dc-up.
+
+This module parses arguments and dispatches commands.
+Command behavior lives in dc_up.commands.
+
+Commands:
+uv run dc-up
+uv run dc-up --write
+uv run dc-up todo
+
+Equivalent uvx usage after release:
+uvx dc-up
+uvx dc-up --write
+uvx dc-up todo
+"""
+
+import argparse
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from dc_up.commands import todo, update
+
+__all__ = ["build_parser", "main"]
+
+CommandFunc = Callable[[argparse.Namespace], int]
+
+EXIT_OK = 0
+EXIT_NO_COMMAND = 2
+
+
+def _run_update(args: argparse.Namespace) -> int:
+    """Bring the current repository up to the managed baseline."""
+    return update.run(
+        root=args.root,
+        write=args.write,
+        templates=args.templates,
+        ref=args.ref,
+        templates_path=args.templates_path,
+    )
+
+
+def _run_todo(args: argparse.Namespace) -> int:
+    """Show repo-specific human work that dc-up cannot safely calculate."""
+    return todo.run(root=args.root)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="dc-up",
+        description=(
+            "Bring the current repository up to the current Denise Case "
+            "managed baseline from canonical templates."
+        ),
+    )
+
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help=(
+            "Repository root to update. Defaults to the nearest parent "
+            "directory containing .git, or the current directory."
+        ),
+    )
+    parser.add_argument(
+        "--write",
+        action="store_true",
+        help=(
+            "Apply managed baseline changes. Without this flag, dc-up performs "
+            "a dry run and reports what would change."
+        ),
+    )
+    parser.add_argument(
+        "--templates",
+        default="denisecase/templates",
+        help=(
+            "GitHub owner/repo for canonical templates. "
+            "Defaults to denisecase/templates."
+        ),
+    )
+    parser.add_argument(
+        "--ref",
+        default="main",
+        help="Git ref, branch, or tag to fetch templates from. Defaults to main.",
+    )
+    parser.add_argument(
+        "--templates-path",
+        type=Path,
+        default=None,
+        help=(
+            "Optional local templates repository path. If provided, templates "
+            "are read from disk instead of GitHub raw URLs."
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=False)
+
+    # === TODO COMMAND ===
+
+    todo_parser = subparsers.add_parser(
+        "todo",
+        help=(
+            "Show repo-specific human review work that cannot be safely "
+            "calculated or overwritten."
+        ),
+    )
+    todo_parser.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help=(
+            "Repository root to inspect. Defaults to the nearest parent "
+            "directory containing .git, or the current directory."
+        ),
+    )
+    todo_parser.set_defaults(func=_run_todo)
+
+    parser.set_defaults(func=_run_update)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command-line interface.
+
+    Args:
+        argv: Optional command-line arguments. If None, uses sys.argv.
+
+    Returns:
+        Exit code from the executed command.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    func: CommandFunc | None = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return EXIT_NO_COMMAND
+
+    return func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dc_up/commands/__init__.py

@@ -0,0 +1,11 @@
+"""Command modules for dc-up.
+
+Each command module exposes a stable run(...) -> int entry point.
+
+The CLI parser lives in dc_up.cli.
+Behavior lives here.
+"""
+
+from dc_up.commands import todo, update
+
+__all__ = ["todo", "update"]

dc_up/commands/todo.py

@@ -0,0 +1,23 @@
+"""Print repo-specific human review work for dc-up."""
+
+from pathlib import Path
+
+from dc_up.detect import detect_repository
+from dc_up.todo import build_todo_report, print_todo_report
+
+__all__ = ["run"]
+
+
+def run(*, root: Path | None = None) -> int:
+    """Show non-calculatable repo-specific work.
+
+    Args:
+        root: Repository root. If None, dc-up detects the current repo root.
+
+    Returns:
+        Process exit code.
+    """
+    repository = detect_repository(root)
+    report = build_todo_report(repository)
+    print_todo_report(report)
+    return 0

dc_up/commands/update.py

@@ -0,0 +1,50 @@
+"""Apply or preview the managed repository baseline."""
+
+from pathlib import Path
+
+from dc_up.detect import detect_repository
+from dc_up.fetch import TemplateSource
+from dc_up.plan import build_update_plan, print_update_plan, write_update_plan
+
+__all__ = ["run"]
+
+
+def run(
+    *,
+    root: Path | None = None,
+    write: bool = False,
+    templates: str = "denisecase/templates",
+    ref: str = "main",
+    templates_path: Path | None = None,
+) -> int:
+    """Preview or apply managed baseline updates.
+
+    Args:
+        root: Repository root. If None, dc-up detects the current repo root.
+        write: Whether to write changes. False means dry-run only.
+        templates: GitHub owner/repo for canonical templates.
+        ref: Git ref, branch, or tag.
+        templates_path: Optional local templates repo path.
+
+    Returns:
+        Process exit code.
+    """
+    repository = detect_repository(root)
+
+    source = TemplateSource(
+        repository=templates,
+        ref=ref,
+        local_path=templates_path,
+    )
+
+    plan = build_update_plan(
+        target=repository,
+        source=source,
+    )
+
+    print_update_plan(plan, write=write)
+
+    if write:
+        write_update_plan(plan)
+
+    return 0

dc_up/detect.py

@@ -0,0 +1,124 @@
+"""Repository detection."""
+
+import configparser
+from pathlib import Path
+import re
+
+from dc_up.baseline import infer_layers
+from dc_up.errors import RepositoryDetectionError
+from dc_up.types import RepositoryContext
+
+__all__ = ["detect_repository"]
+
+
+GITHUB_REMOTE_RE = re.compile(
+    r"(?:git@github\.com:|https://github\.com/)(?P<repo>[^/\s]+/[^/\s]+?)(?:\.git)?/?$"
+)
+
+
+def detect_repository(root: Path | None = None) -> RepositoryContext:
+    """Detect the repository context.
+
+    Args:
+        root: Optional repository root. If None, detect from current directory.
+
+    Returns:
+        Repository context used by planning and TODO generation.
+
+    Raises:
+        RepositoryDetectionError: If the target directory cannot be resolved.
+    """
+    repo_root = _resolve_repo_root(root)
+    files = _snapshot_files(repo_root)
+
+    repo_slug = repo_root.name
+    repo_name = _detect_repo_name(repo_root) or f"denisecase/{repo_slug}"
+
+    repo_url = f"https://github.com/{repo_name}"
+    site_url = f"https://denisecase.github.io/{repo_slug}/"
+
+    layers = tuple(infer_layers(repo_root=repo_root, repo_slug=repo_slug, files=files))
+
+    return RepositoryContext(
+        root=repo_root,
+        repo_slug=repo_slug,
+        repo_name=repo_name,
+        repo_url=repo_url,
+        site_url=site_url,
+        files=frozenset(files),
+        layers=layers,
+    )
+
+
+def _resolve_repo_root(root: Path | None) -> Path:
+    """Resolve the target repository root."""
+    start = Path.cwd() if root is None else root
+    start = start.expanduser().resolve()
+
+    if not start.exists():
+        raise RepositoryDetectionError(f"Repository path does not exist: {start}")
+
+    if start.is_file():
+        start = start.parent
+
+    for candidate in [start, *start.parents]:
+        if (candidate / ".git").exists():
+            return candidate
+
+    return start
+
+
+def _snapshot_files(root: Path) -> set[str]:
+    """Return repository-relative file and directory markers."""
+    result: set[str] = set()
+
+    ignored_dirs = {
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".venv",
+        "__pycache__",
+        "dist",
+        "build",
+        "htmlcov",
+        "node_modules",
+    }
+
+    for path in root.rglob("*"):
+        rel = path.relative_to(root).as_posix()
+
+        if any(part in ignored_dirs for part in path.parts):
+            continue
+
+        if path.is_dir():
+            result.add(rel)
+            result.add(f"{rel}/")
+        else:
+            result.add(rel)
+
+    return result
+
+
+def _detect_repo_name(root: Path) -> str | None:
+    """Infer owner/repo from .git/config if possible."""
+    git_config = root / ".git" / "config"
+    if not git_config.exists():
+        return None
+
+    parser = configparser.ConfigParser()
+    try:
+        parser.read(git_config, encoding="utf-8")
+    except configparser.Error:
+        return None
+
+    section = 'remote "origin"'
+    if not parser.has_section(section):
+        return None
+
+    url = parser.get(section, "url", fallback="")
+    match = GITHUB_REMOTE_RE.search(url.strip())
+    if match is None:
+        return None
+
+    return match.group("repo")

dc_up/errors.py

@@ -0,0 +1,38 @@
+"""Exception types for dc-up."""
+
+from pathlib import Path
+
+__all__ = [
+    "DcUpError",
+    "RepositoryDetectionError",
+    "TemplateFetchError",
+    "UnsafePathError",
+]
+
+
+class DcUpError(Exception):
+    """Base exception for dc-up."""
+
+
+class RepositoryDetectionError(DcUpError):
+    """Raised when dc-up cannot determine the target repository."""
+
+    def __init__(self, message: str) -> None:
+        """Initialize the error."""
+        super().__init__(message)
+
+
+class TemplateFetchError(DcUpError):
+    """Raised when template content cannot be fetched."""
+
+    def __init__(self, message: str) -> None:
+        """Initialize the error."""
+        super().__init__(message)
+
+
+class UnsafePathError(DcUpError):
+    """Raised when a path would escape the target repository."""
+
+    def __init__(self, path: Path) -> None:
+        """Initialize the error."""
+        super().__init__(f"Unsafe path escapes repository root: {path}")