karni-cli 0.3.1__py3-none-any.whl

karni_cli/tips.py

@@ -0,0 +1,53 @@
+"""One-time suggestions, done honestly.
+
+A tip names what it would add and who made it, appears at most once per
+project (recorded in the untracked ``.karni/local/state.json``), and never:
+
+* in CI (:func:`karni_cli.environment.is_ci`);
+* with ``suggest_tools = false`` (``karni config set suggest_tools false``,
+  project or ``--global``) or a quiet flag (``-q``);
+* when it no longer applies (here: a history provider is already present);
+* in machine-readable output — only ``karni doctor`` and ``karni check`` ask
+  for tips; ``karni context``, ``karni types``, ``karni rules`` and
+  ``karni new`` never do.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from karni_cli import config, history, local_state
+from karni_cli.environment import is_ci
+from karni_cli.project import CliError
+
+HISTORY_TIP_ID = "history-provider"
+
+#: The authorship disclosure is part of the tip, not optional.
+HISTORY_TIP = (
+    "tip: no prompt-history store found. `karni context --with-history` can brief\n"
+    "     an agent with what was already asked about a file. Works with Gigai\n"
+    "     Chronicle (MIT, local-only, by Karni's author).\n"
+    "     Silence this: karni config set suggest_tools false"
+)
+
+
+def history_tip(project: Path | None, *, quiet: bool = False) -> str | None:
+    """The history-provider tip if it may be shown now, else ``None``.
+
+    Returning the text records it as shown; if that record cannot be written
+    the tip is not shown at all, so it can never repeat.
+    """
+    if quiet or project is None or is_ci():
+        return None
+    try:
+        if not config.resolve("suggest_tools", project).value:
+            return None
+    except CliError:
+        return None  # an unreadable config file: stay silent rather than guess
+    if local_state.tip_shown(project, HISTORY_TIP_ID):
+        return None
+    if history.provider_present(project):
+        return None
+    if not local_state.mark_tip_shown(project, HISTORY_TIP_ID):
+        return None
+    return HISTORY_TIP

karni_cli/typegen.py

@@ -0,0 +1,101 @@
+"""Typed-hook generation for ``karni types`` (E2).
+
+The item component for each resource is resolved by following the list
+operation's 200 response ``$ref`` through the paginated wrapper to
+``properties.results.items.$ref`` — never derived from the resource name
+(component names are app-qualified, e.g. ``TestappEvent``).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from karni_cli.project import CliError
+
+HEADER = "// generated by karni types — do not edit\n"
+
+
+def load_schema(path: Path) -> dict[str, Any]:
+    text = path.read_text()
+    if path.suffix == ".json":
+        return json.loads(text)
+    return yaml.safe_load(text)
+
+
+def _resolve(doc: dict[str, Any], ref: str) -> dict[str, Any]:
+    if not ref.startswith("#/"):
+        raise CliError(f"Unsupported external $ref: {ref}", code="C206")
+    node: Any = doc
+    for part in ref[2:].split("/"):
+        node = node[part]
+    return node
+
+
+def _component_name(ref: str) -> str:
+    return ref.rsplit("/", 1)[-1]
+
+
+def resource_components(doc: dict[str, Any]) -> dict[str, str]:
+    """resource → item component name, from list ops carrying x-karni-resource."""
+    out: dict[str, str] = {}
+    for _path, item in sorted(doc.get("paths", {}).items()):
+        op = item.get("get")
+        if not op:
+            continue
+        resource = op.get("x-karni-resource")
+        if not resource or resource in out:
+            continue
+        try:
+            ref = op["responses"]["200"]["content"]["application/json"]["schema"]["$ref"]
+            paginated = _resolve(doc, ref)
+            items_ref = paginated["properties"]["results"]["items"]["$ref"]
+        except (KeyError, TypeError):
+            continue  # not a paginated list response; skip quietly
+        out[resource] = _component_name(items_ref)
+    return out
+
+
+def _pascal(resource: str) -> str:
+    return "".join(part.capitalize() for part in resource.replace("-", "_").split("_"))
+
+
+def generate_hooks(doc: dict[str, Any]) -> str:
+    resources = resource_components(doc)
+    if not resources:
+        raise CliError("No x-karni-resource list operations found in the schema.", code="C206")
+    lines = [
+        HEADER.rstrip("\n"),
+        'import { useResourceItem, useResourceList, useResourceMutations } from "@karni/ui";',
+        "import type {",
+        "  ResourceItemParams,",
+        "  ResourceListParams,",
+        "  ResourceMutationsOptions,",
+        '} from "@karni/ui";',
+        'import type { components } from "./types";',
+        "",
+    ]
+    for resource, component in sorted(resources.items()):
+        name = _pascal(resource)
+        item = f'components["schemas"]["{component}"]'
+        lines += [
+            f"export type {name}Item = {item};",
+            f"export const use{name}List = (params?: ResourceListParams) =>",
+            f'  useResourceList<{item}>("{resource}", params);',
+            f"export const use{name}Item = (id: string | number, params?: ResourceItemParams) =>",
+            f'  useResourceItem<{item}>("{resource}", id, params);',
+            f"export const use{name}Mutations = (options?: ResourceMutationsOptions) =>",
+            f'  useResourceMutations<{item}>("{resource}", options);',
+            "",
+        ]
+    return "\n".join(lines)
+
+
+def write_hooks(schema_path: Path, out_dir: Path) -> Path:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    hooks = out_dir / "hooks.ts"
+    hooks.write_text(generate_hooks(load_schema(schema_path)))
+    return hooks

karni_cli/upgrades/__init__.py

@@ -0,0 +1,28 @@
+"""``karni upgrade``: move a project across Karni versions with the changelog's codemods.
+
+* :mod:`.changelog` — Karni's machine-readable changelog (one TOML file per
+  release in ``packages/karni/karni/changelog``) and the selection of the
+  changes between two versions;
+* :mod:`.codemod` — the codemod contract, and which project files it may touch;
+* :mod:`.python` — data-driven libcst codemods (rename a symbol or a setting,
+  replace an attribute or a method call) and detectors for manual changes;
+* :mod:`.typescript` — the pinned jscodeshift runner and its data-driven
+  transforms (``transforms/``);
+* :mod:`.engine` — runs codemods over a scratch copy, diffs it, writes it
+  back all or nothing, and builds the report;
+* ``v<major>_<minor>/<name>.py`` — one module per breaking change, named by
+  the release in which the old form breaks, exposing ``CODEMOD``.
+
+Recording a breaking change:
+
+1. append a ``[[change]]`` to ``packages/karni/karni/changelog/<release>.toml``;
+2. if it is mechanical, add ``upgrades/v<X>_<Y>/<name>.py``, usually one line
+   of data (``CODEMOD = RenameSymbol(old=..., new=...)``,
+   ``RenameSetting(...)``, ``RenameExport(...)`` for ``@karni/ui``), plus a
+   before/after test; if it is manual, optionally a detector the same way;
+3. write its section in ``docs/migrations/<release>.md``; if it deprecates
+   something, ``warn_deprecated(..., removed_in=..., doc_anchor=<that section>)``.
+
+The changelog tests (packages/karni/tests/test_changelog.py,
+tests/test_upgrade.py here) fail until every piece is in place.
+"""

karni_cli/upgrades/changelog.py

@@ -0,0 +1,123 @@
+"""Karni's machine-readable changelog, as karni-cli reads it, and version selection.
+
+The data and its schema live in Karni (``packages/karni/karni/changelog``).
+That package is stdlib only, so the CLI loads it by path and never imports
+Karni or Django: from the monorepo source when run from a checkout, else from
+the copy bundled into the wheel (``karni_cli/_changelog``, see hatch_build.py).
+The CLI therefore knows every change up to its own release, whichever karni
+the project has installed. That is what lets ``karni upgrade`` run *before*
+the project raises its karni pin.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from collections.abc import Iterable, Sequence
+from importlib import resources
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+from packaging.version import InvalidVersion, Version
+
+from karni_cli.project import CliError
+
+if TYPE_CHECKING:
+    from karni.changelog import Change
+
+_MODULE_NAME = "karni_cli._bundled_karni_changelog"
+
+
+def source_dir() -> Path | None:
+    """The changelog package: the monorepo source, else the wheel's bundled copy."""
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "packages" / "karni" / "karni" / "changelog"
+        if (candidate / "__init__.py").is_file():
+            return candidate
+    packaged = resources.files("karni_cli") / "_changelog"
+    with resources.as_file(packaged) as path:
+        if (path / "__init__.py").is_file():
+            return path
+    return None
+
+
+def module() -> ModuleType:
+    """``karni.changelog``, loaded by path under a private name."""
+    if _MODULE_NAME in sys.modules:
+        return sys.modules[_MODULE_NAME]
+    directory = source_dir()
+    if directory is None:
+        raise CliError(
+            "Karni's changelog is missing from this karni-cli install "
+            "(karni_cli/_changelog). Reinstall karni-cli.",
+            code="C005",
+        )
+    spec = importlib.util.spec_from_file_location(_MODULE_NAME, directory / "__init__.py")
+    if spec is None or spec.loader is None:  # pragma: no cover - importlib contract
+        raise CliError(f"Cannot load Karni's changelog from {directory}", code="C005")
+    loaded = importlib.util.module_from_spec(spec)
+    sys.modules[_MODULE_NAME] = loaded
+    try:
+        spec.loader.exec_module(loaded)
+    except Exception:
+        del sys.modules[_MODULE_NAME]
+        raise
+    return loaded
+
+
+def load(directory: Path | None = None) -> list[Change]:
+    """Every recorded change, oldest release first (see ``karni.changelog.load``)."""
+    changelog = module()
+    try:
+        return list(changelog.changes(directory or source_dir()))
+    except changelog.ChangelogError as exc:
+        raise CliError(str(exc.args[0]) if exc.args else str(exc), code="E704") from None
+
+
+def docs_url(anchor: str) -> str:
+    """The published link to a migration note (Karni's single ``DOCS_BASE_URL``)."""
+    return str(module().docs_url(anchor))
+
+
+def parse(version: str, what: str) -> Version:
+    try:
+        return Version(version)
+    except InvalidVersion:
+        raise CliError(
+            f"{what} {version!r} is not a version number (e.g. 0.2.0).", code="C203"
+        ) from None
+
+
+def newest_release(changes: Iterable[Change]) -> str:
+    """The default ``--to``: the newest release that recorded a change."""
+    releases = {change.release for change in changes}
+    return max(releases, key=Version) if releases else "0"
+
+
+def horizon(changes: Iterable[Change]) -> Version:
+    """The newest version this changelog knows anything about (a release or a removal)."""
+    versions = [Version(c.release) for c in changes] + [
+        Version(c.removed_in) for c in changes if c.removed_in
+    ]
+    return max(versions, default=Version("0"))
+
+
+def select(changes: Sequence[Change], current: str, target: str) -> list[Change]:
+    """The changes to apply moving ``current`` -> ``target``, in the order to apply them.
+
+    A change is selected when its replacement exists in the target
+    (``release <= target``) and the project has not yet passed the release
+    where the old form breaks (``current < breaks_in``). So a deprecation is
+    picked up by every upgrade from before its removal, including one from
+    the very release that deprecated it, and moving to that release fixes
+    the warnings before they break anything. Order: by the release that
+    breaks, then the release that introduced, then file order.
+    """
+    now, then = Version(current), Version(target)
+    picked = [
+        change
+        for change in changes
+        if Version(change.release) <= then and now < Version(change.breaks_in)
+    ]
+    return sorted(picked, key=lambda c: (Version(c.breaks_in), Version(c.release)))

karni_cli/upgrades/codemod.py

@@ -0,0 +1,125 @@
+"""The codemod contract, and which project files a codemod may touch.
+
+A codemod is one breaking change made mechanical. It runs over a directory
+tree (the engine hands it a scratch copy of the project), edits files in
+place and returns an :class:`Outcome`: the files it changed with a count of
+rewrites each, the :class:`Site` list it could not fix safely, or why it
+did not run at all. A *detector* (``edits = False``) never edits: it finds
+the code that a manual change has to touch.
+
+Codemods are addressed by id, ``v<major>_<minor>.<name>``: the module
+``karni_cli.upgrades.v1_0.all_objects_to_without`` exposes ``CODEMOD``.
+The version is the release in which the old form breaks.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import ClassVar
+
+#: Directories never copied or scanned: VCS data, virtualenvs, installed
+#: dependencies, caches, build output, uploaded and collected files.
+PRUNE: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "node_modules",
+        "site-packages",
+        "dist-packages",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".nox",
+        "dist",
+        "build",
+        "media",
+        "staticfiles",
+    }
+)
+#: Also skipped when looking for source to rewrite: migrations are history
+#: (they must keep replaying as written) and .karni/ holds Karni's own files.
+SOURCE_PRUNE: frozenset[str] = PRUNE | {"migrations", ".karni"}
+
+
+def walk(root: Path, prune: frozenset[str] = PRUNE) -> Iterator[Path]:
+    """Every regular file under ``root``, skipping ``prune`` and any virtualenv.
+
+    Path-based, like Karni's project-code discovery: what lives under the
+    project root is the project's, except dependencies and generated trees.
+    Symbolic links are never followed or yielded.
+    """
+    for directory, dirnames, filenames in os.walk(root):
+        here = Path(directory)
+        dirnames[:] = sorted(
+            name
+            for name in dirnames
+            if name not in prune
+            and not (here / name).is_symlink()
+            and not (here / name / "pyvenv.cfg").is_file()
+        )
+        for name in sorted(filenames):
+            path = here / name
+            if not path.is_symlink():
+                yield path
+
+
+def source_files(root: Path, suffixes: tuple[str, ...]) -> list[str]:
+    """Project-relative POSIX paths of the project's own source files."""
+    return [
+        path.relative_to(root).as_posix()
+        for path in walk(root, SOURCE_PRUNE)
+        if path.name.endswith(suffixes)
+    ]
+
+
+@dataclass(frozen=True)
+class Site:
+    """A place in the project that needs a person."""
+
+    path: str
+    line: int
+    note: str
+
+    def render(self) -> str:
+        where = f"{self.path}:{self.line}" if self.line else self.path
+        return f"{where}: {self.note}"
+
+
+@dataclass
+class Outcome:
+    #: project-relative path -> number of rewrites in it
+    files: dict[str, int] = field(default_factory=dict)
+    #: code the codemod found but could not (or must not) rewrite
+    sites: list[Site] = field(default_factory=list)
+    #: why the codemod did not run (empty when it did)
+    skipped: str = ""
+
+
+class Codemod(ABC):
+    """One breaking change, made mechanical (or, with ``edits = False``, findable)."""
+
+    #: False for a detector: it reports sites and never edits.
+    edits: ClassVar[bool] = True
+
+    @abstractmethod
+    def apply(self, root: Path) -> Outcome:
+        """Rewrite the tree under ``root`` in place and say what happened."""
+
+
+def load_codemod(codemod_id: str) -> Codemod:
+    """``"v1_0.all_objects_to_without"`` -> that module's ``CODEMOD``."""
+    module = importlib.import_module(f"karni_cli.upgrades.{codemod_id}")
+    codemod = getattr(module, "CODEMOD", None)
+    if not isinstance(codemod, Codemod):
+        raise TypeError(f"karni_cli.upgrades.{codemod_id} must define CODEMOD (a Codemod)")
+    return codemod

karni_cli/upgrades/engine.py

@@ -0,0 +1,224 @@
+"""Run the selected changes' codemods: all or nothing, with a diff and a report.
+
+Every codemod runs, in order, over a scratch copy of the project (the
+project's own files, without .git, virtualenvs, node_modules, caches or
+build output; ``.venv`` is linked in so project-interpreter lookups still
+work). Then the copy is compared with the project:
+
+* ``dry_run``: the unified diff is returned and the project is untouched;
+* otherwise every changed, added or removed file is written back, and only
+  after every codemod succeeded. A failing codemod leaves the project as it
+  was.
+
+Each change lands in the report as *applied* (files and rewrite counts),
+*manual* (sites a person must change, plus every manual change, with its
+migration note) and/or *skipped* (nothing to change, or could not run).
+"""
+
+from __future__ import annotations
+
+import difflib
+import os
+import shutil
+import tempfile
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from karni_cli.project import CliError
+from karni_cli.upgrades import changelog as changelog_mod
+from karni_cli.upgrades.codemod import Codemod, Outcome, Site, load_codemod, walk
+
+if TYPE_CHECKING:
+    from karni.changelog import Change
+
+#: Files larger than this are not copied: no codemod rewrites them.
+MAX_BYTES = 5 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class FileChange:
+    path: str
+    before: bytes | None  # None: the codemods created it
+    after: bytes | None  # None: the codemods removed it
+
+
+@dataclass
+class Report:
+    current: str
+    target: str
+    dry_run: bool
+    applied: list[tuple[Change, Outcome]] = field(default_factory=list)
+    manual: list[tuple[Change, list[Site]]] = field(default_factory=list)
+    skipped: list[tuple[Change, str]] = field(default_factory=list)
+    changes: list[FileChange] = field(default_factory=list)
+
+    @property
+    def diff(self) -> str:
+        return unified_diff(self.changes)
+
+
+# the scratch copy
+
+
+def _copy(project: Path, scratch: Path) -> set[str]:
+    """Copy the project's files into ``scratch``; returns their relative paths."""
+    copied: set[str] = set()
+    for path in walk(project):
+        if path.stat().st_size > MAX_BYTES:
+            continue
+        rel = path.relative_to(project).as_posix()
+        target = scratch / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, target)
+        copied.add(rel)
+    venv = project / ".venv"
+    if venv.is_dir():
+        os.symlink(venv, scratch / ".venv", target_is_directory=True)
+    return copied
+
+
+def _compare(project: Path, scratch: Path, copied: set[str]) -> list[FileChange]:
+    found: list[FileChange] = []
+    for rel in sorted(copied):
+        before = (project / rel).read_bytes()
+        result = scratch / rel
+        after = result.read_bytes() if result.is_file() else None
+        if after != before:
+            found.append(FileChange(rel, before, after))
+    for path in walk(scratch):
+        rel = path.relative_to(scratch).as_posix()
+        if rel not in copied:
+            found.append(FileChange(rel, None, path.read_bytes()))
+    return sorted(found, key=lambda change: change.path)
+
+
+def _write_back(project: Path, scratch: Path, changes: Sequence[FileChange]) -> None:
+    for change in changes:
+        target = project / change.path
+        if change.after is None:
+            target.unlink(missing_ok=True)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(scratch / change.path, target)
+
+
+def unified_diff(changes: Sequence[FileChange]) -> str:
+    """``git diff``-style text for ``changes`` (new files from /dev/null, removals to it)."""
+    chunks: list[str] = []
+    for change in changes:
+        old_name = f"a/{change.path}" if change.before is not None else "/dev/null"
+        new_name = f"b/{change.path}" if change.after is not None else "/dev/null"
+        try:
+            old = (change.before or b"").decode("utf-8")
+            new = (change.after or b"").decode("utf-8")
+        except UnicodeDecodeError:
+            chunks.append(f"Binary files {old_name} and {new_name} differ\n")
+            continue
+        lines = list(
+            difflib.unified_diff(
+                old.splitlines(keepends=True),
+                new.splitlines(keepends=True),
+                fromfile=old_name,
+                tofile=new_name,
+            )
+        )
+        chunks.append(
+            "".join(
+                line if line.endswith("\n") else line + "\n\\n"
+                for line in lines
+            )
+        )
+    return "".join(chunks)
+
+
+# running
+
+
+def _record(report: Report, change: Change, codemod: Codemod, outcome: Outcome) -> None:
+    if outcome.skipped:
+        report.skipped.append((change, outcome.skipped))
+    if outcome.files:
+        report.applied.append((change, outcome))
+    if outcome.sites:
+        report.manual.append((change, outcome.sites))
+    elif not outcome.files and not outcome.skipped:
+        report.skipped.append((change, "nothing to change" if codemod.edits else "no uses found"))
+
+
+def run(
+    project: Path,
+    changes: Sequence[Change],
+    *,
+    current: str,
+    target: str,
+    dry_run: bool,
+    resolve: Callable[[str], Codemod] = load_codemod,
+) -> Report:
+    """Apply ``changes`` (already selected and ordered) to ``project``."""
+    report = Report(current=current, target=target, dry_run=dry_run)
+    with tempfile.TemporaryDirectory(prefix="karni-upgrade-") as tmp:
+        scratch = Path(tmp) / project.name
+        scratch.mkdir()
+        copied = _copy(project, scratch)
+        for change in changes:
+            if not change.codemod:
+                report.manual.append((change, []))
+                continue
+            codemod = resolve(change.codemod)
+            try:
+                outcome = codemod.apply(scratch)
+            except Exception as exc:
+                raise CliError(
+                    f"codemod {change.codemod} ({change.id}) failed: {exc!r}. "
+                    "Nothing was written; please report this with the file it stopped on.",
+                    code="C199",
+                ) from exc
+            _record(report, change, codemod, outcome)
+        report.changes = _compare(project, scratch, copied)
+        if not dry_run:
+            _write_back(project, scratch, report.changes)
+    return report
+
+
+# the report
+
+
+def _title(change: Change) -> str:
+    arrow = f" -> {change.replacement}" if change.replacement else ""
+    return f"{change.id}: {change.symbol}{arrow}"
+
+
+def render(report: Report) -> str:
+    """The human report: applied, could not fix automatically, skipped, next steps."""
+    verb = "Would apply" if report.dry_run else "Applied"
+    lines: list[str] = []
+    if report.applied:
+        lines.append(f"{verb} automatically:")
+        for change, outcome in report.applied:
+            lines.append(f"  {_title(change)}  [{change.codemod}]")
+            lines += [f"      {path}: {count}" for path, count in sorted(outcome.files.items())]
+    if report.manual:
+        lines.append("Could not fix automatically (needs you):")
+        for change, sites in report.manual:
+            lines.append(f"  {_title(change)}")
+            if not sites:
+                lines.append(f"      {change.summary}")
+            lines += [f"      {site.render()}" for site in sites]
+            lines.append(f"      see {changelog_mod.docs_url(change.migration)}")
+    if report.skipped:
+        lines.append("Skipped:")
+        lines += [f"  {change.id}: {reason}" for change, reason in report.skipped]
+    files = len(report.changes)
+    if report.dry_run:
+        lines.append(f"Dry run: {files} file(s) would change; nothing was written.")
+    else:
+        lines.append(f"{files} file(s) changed.")
+        lines.append(
+            f"Next: review `git diff`, pin karni to {report.target} and reinstall, make the "
+            "changes listed above, run your formatter (rewrites keep your style but do not "
+            "re-wrap long lines), then `karni check` and your tests with "
+            "-W error::karni.deprecation.KarniDeprecationWarning."
+        )
+    return "\n".join(lines)