karni-cli 0.3.1__py3-none-any.whl

karni_cli/upgrades/transforms/rename-export.cjs

@@ -0,0 +1,96 @@
+/**
+ * jscodeshift transform: rename one named export of a module at every use site.
+ *
+ * Driven by data (karni_cli.upgrades.typescript.RenameExport), never edited
+ * per change. Options:
+ *   --karni-module=@karni/ui  --karni-from=OldName  --karni-to=NewName
+ *
+ *   import { Old } from "mod"         -> import { New } from "mod"   (+ every reference)
+ *   import { Old as X } from "mod"    -> import { New as X } from "mod"
+ *   export { Old } from "mod"         -> export { New as Old } from "mod"  (your export keeps its name)
+ *
+ * References are renamed only where `Old` resolves to the module-level
+ * import, so a local variable or parameter that shadows it is left alone,
+ * as are object keys and member names. Reports `karni-count <n>` per file.
+ */
+module.exports = function renameExport(file, api, options) {
+  const j = api.jscodeshift;
+  const mod = options["karni-module"];
+  const from = options["karni-from"];
+  const to = options["karni-to"];
+  if (!mod || !from || !to) {
+    throw new Error("rename-export needs --karni-module, --karni-from and --karni-to");
+  }
+  const root = j(file.source);
+  const program = root.find(j.Program).paths()[0];
+  const bindsToImport = (path) => path.scope != null && path.scope.lookup(from) === program.scope;
+
+  const specifiers = [];
+  let unaliased = false;
+  root.find(j.ImportDeclaration, { source: { value: mod } }).forEach((path) => {
+    for (const spec of path.node.specifiers || []) {
+      if (spec.type !== "ImportSpecifier" || spec.imported.name !== from) continue;
+      specifiers.push(spec);
+      if (!spec.local || spec.local.name === from) unaliased = true;
+    }
+  });
+
+  // Collect references before renaming anything: scope lookups use the old name.
+  // A Set: the AST walk can reach one JSX tag name through two paths.
+  const references = new Set();
+  if (unaliased) {
+    root
+      .find(j.Identifier, { name: from })
+      .filter((path) => {
+        const parent = path.parent.node;
+        if (parent.type === "ImportSpecifier" || parent.type === "ExportSpecifier") return false;
+        const member =
+          parent.type === "MemberExpression" || parent.type === "OptionalMemberExpression";
+        if (member && parent.property === path.node && !parent.computed) return false;
+        const keyed =
+          parent.type === "Property" ||
+          parent.type === "ObjectProperty" ||
+          parent.type === "ClassProperty" ||
+          parent.type === "TSPropertySignature";
+        if (keyed && parent.key === path.node && !parent.computed) return false;
+        if (parent.type === "TSQualifiedName" && parent.right === path.node) return false;
+        return bindsToImport(path);
+      })
+      .forEach((path) => references.add(path.node));
+    root
+      .find(j.JSXIdentifier, { name: from })
+      .filter((path) => {
+        const parent = path.parent.node;
+        const tag =
+          parent.type === "JSXOpeningElement" ||
+          parent.type === "JSXClosingElement" ||
+          (parent.type === "JSXMemberExpression" && parent.object === path.node);
+        return tag && bindsToImport(path);
+      })
+      .forEach((path) => references.add(path.node));
+  }
+
+  let count = 0;
+  for (const spec of specifiers) {
+    const aliased = spec.local && spec.local.name !== from;
+    spec.imported = j.identifier(to);
+    if (!aliased) spec.local = j.identifier(to);
+    count += 1;
+  }
+  for (const node of references) {
+    node.name = to;
+    count += 1;
+  }
+  root.find(j.ExportNamedDeclaration, { source: { value: mod } }).forEach((path) => {
+    path.node.specifiers = (path.node.specifiers || []).map((spec) => {
+      if (spec.type !== "ExportSpecifier" || spec.local.name !== from) return spec;
+      count += 1;
+      const exported = spec.exported ? spec.exported.name : from;
+      return j.exportSpecifier.from({ local: j.identifier(to), exported: j.identifier(exported) });
+    });
+  });
+
+  if (count === 0) return null;
+  api.report(`karni-count ${count}`);
+  return root.toSource();
+};

karni_cli/upgrades/typescript.py

@@ -0,0 +1,160 @@
+"""TypeScript codemods: jscodeshift, run through the machine's own Node.js.
+
+The CLI ships the transforms (``karni_cli/upgrades/transforms/``) and runs
+them with a pinned jscodeshift through ``npx``, so a project needs nothing
+installed beyond Node.js itself. Without Node.js, a TypeScript codemod
+reports itself skipped (naming how many files need it) instead of failing
+the upgrade. Files are pre-filtered in Python, so a project with nothing to
+change never needs Node.js at all.
+
+A breaking ``@karni/ui`` change is one line of data in its version module::
+
+    CODEMOD = RenameExport(module="@karni/ui", old="DataTable", new="ResourceTable")
+
+Override / escape hatch: ``KARNI_JSCODESHIFT`` replaces the whole runner
+command (e.g. ``"node /path/to/jscodeshift/bin/jscodeshift.js"`` for an
+offline machine); subclass :class:`JscodeshiftCodemod` with a new transform
+for a change that is not a rename.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+from abc import abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar, Final
+
+from karni_cli.upgrades.codemod import Codemod, Outcome, source_files
+
+__all__ = [
+    "JSCODESHIFT_VERSION",
+    "JscodeshiftCodemod",
+    "RenameExport",
+    "jscodeshift_command",
+]
+
+#: Pinned so a codemod behaves the same on every machine, every run.
+JSCODESHIFT_VERSION: Final = "17.4.0"
+TRANSFORMS: Final = Path(__file__).resolve().parent / "transforms"
+#: Seconds one jscodeshift run may take (the first npx run also downloads it).
+TIMEOUT: Final = 600
+SUFFIXES: Final = (".ts", ".tsx", ".mts", ".cts")
+_REPORT = re.compile(r"^\s*REP (?P<path>.+) karni-count (?P<count>\d+)\s*$", re.MULTILINE)
+
+
+def jscodeshift_command() -> list[str] | None:
+    """``KARNI_JSCODESHIFT``, else ``npx --yes jscodeshift@<pin>``; None without Node.js."""
+    override = os.environ.get("KARNI_JSCODESHIFT", "").strip()
+    if override:
+        return shlex.split(override)
+    npx = shutil.which("npx")
+    return [npx, "--yes", f"jscodeshift@{JSCODESHIFT_VERSION}"] if npx else None
+
+
+class JscodeshiftCodemod(Codemod):
+    """A codemod that runs one transform from ``transforms/`` over the TypeScript files."""
+
+    #: File name of the transform under ``karni_cli/upgrades/transforms/``.
+    transform: ClassVar[str]
+
+    @abstractmethod
+    def needles(self) -> tuple[str, ...]:
+        """A file is handed to jscodeshift only when it contains every one of these."""
+
+    @abstractmethod
+    def options(self) -> list[str]:
+        """Options passed through to the transform (``--name=value``)."""
+
+    def apply(self, root: Path) -> Outcome:
+        needles = [needle.encode() for needle in self.needles()]
+        candidates = [
+            rel
+            for rel in source_files(root, SUFFIXES)
+            if not rel.endswith(".d.ts") and all(n in (root / rel).read_bytes() for n in needles)
+        ]
+        if not candidates:
+            return Outcome()
+        command = jscodeshift_command()
+        if command is None:
+            return Outcome(
+                skipped=f"Node.js (npx) not found, and {len(candidates)} TypeScript file(s) "
+                "need this change: install Node.js 18+ and run karni upgrade again, "
+                "or make it by hand"
+            )
+        before = {rel: (root / rel).read_bytes() for rel in candidates}
+        counts: dict[str, int] = {}
+        groups = (
+            ("tsx", [rel for rel in candidates if rel.endswith(".tsx")]),
+            ("ts", [rel for rel in candidates if not rel.endswith(".tsx")]),
+        )
+        for parser, files in groups:
+            if not files:
+                continue
+            argv = [
+                *command,
+                f"--transform={TRANSFORMS / self.transform}",
+                f"--parser={parser}",
+                "--extensions=ts,tsx,mts,cts",
+                "--no-babel",
+                "--run-in-band",
+                "--fail-on-error",
+                *self.options(),
+                *files,
+            ]
+            try:
+                proc = subprocess.run(
+                    argv,
+                    cwd=root,
+                    text=True,
+                    capture_output=True,
+                    stdin=subprocess.DEVNULL,  # never wait on a prompt
+                    timeout=TIMEOUT,
+                    check=False,
+                )
+            except subprocess.TimeoutExpired:
+                proc = subprocess.CompletedProcess(argv, 124, "", f"timed out after {TIMEOUT}s")
+            except OSError as exc:
+                proc = subprocess.CompletedProcess(argv, 127, "", str(exc))
+            if proc.returncode != 0:
+                for rel, content in before.items():  # never leave a half-run behind
+                    (root / rel).write_bytes(content)
+                detail = (proc.stderr or proc.stdout).strip().splitlines()
+                return Outcome(
+                    skipped=f"jscodeshift failed (exit {proc.returncode}): "
+                    f"{detail[-1] if detail else 'no output'}; make this change by hand"
+                )
+            for match in _REPORT.finditer(proc.stdout):
+                path = match.group("path").strip()
+                counts[path] = counts.get(path, 0) + int(match.group("count"))
+        files_changed = {
+            rel: counts.get(rel, 1)
+            for rel in candidates
+            if (root / rel).read_bytes() != before[rel]
+        }
+        return Outcome(files=files_changed)
+
+
+@dataclass(frozen=True)
+class RenameExport(JscodeshiftCodemod):
+    """``import { old } from "module"`` -> ``import { new } from "module"``, plus every use."""
+
+    transform: ClassVar[str] = "rename-export.cjs"
+
+    module: str
+    old: str
+    new: str
+
+    def needles(self) -> tuple[str, ...]:
+        return (self.module, self.old)
+
+    def options(self) -> list[str]:
+        return [
+            f"--karni-module={self.module}",
+            f"--karni-from={self.old}",
+            f"--karni-to={self.new}",
+        ]

karni_cli/upgrades/v0_2/__init__.py

@@ -0,0 +1 @@
+"""Codemods for changes that break in Karni 0.2 (changelog: karni/changelog/0.2.0.toml)."""

karni_cli/upgrades/v0_2/agent_guidance.py

@@ -0,0 +1,269 @@
+"""Codemod: Karni's hand-written agent files -> karni.rules.py + generated adapters.
+
+Projects scaffolded before the retrofit carry AGENTS.md (canonical guidance),
+CLAUDE.md (``@AGENTS.md``; older projects: the full guidance), .cursorrules
+and .claude/commands/*.md. For each one that is recognisably Karni's:
+
+1. module blocks (``<!-- karni:module:<x> -->``) move to ``.karni/modules/<x>.md``;
+2. every line the project ADDED to Karni's text becomes an ``ADD`` entry in
+   ``karni.rules.py`` (verbatim; grouped per bullet/paragraph; P### codes);
+3. every line the project REMOVED from Karni's text is listed as a
+   ``# REVIEW:`` comment in karni.rules.py and printed — the codemod cannot
+   know whether that meant "disable this rule", so it asks a human;
+4. the original is backed up under ``.karni/backup/`` and replaced by the
+   generated adapter (``karni rules sync``).
+
+Files that do not look like Karni's are left untouched and reported. Nothing
+a user wrote is discarded silently.
+
+Changelog entry ``agent-guidance-files`` (0.2.0); ``CODEMOD`` is what
+``karni upgrade`` runs. :func:`migrate_agent_guidance` is the same migration
+for direct callers, with its own dry run and printed notes.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import typer
+
+from karni_cli import agent_data
+from karni_cli.adapters import MODULES_DIR, backup, is_generated, sync
+from karni_cli.upgrades.codemod import Codemod, Outcome, Site
+from karni_cli.upgrades.legacy_agent_files import LEGACY_FILES, PROJECT_NAME
+
+RULES_FILE = "karni.rules.py"
+#: Line-similarity to a frozen baseline above which a file counts as Karni's.
+SIMILARITY = 0.5
+_MODULE_BLOCK = re.compile(
+    r"<!-- karni:module:(?P<name>[\w-]+) -->\n(?P<body>.*?)\n?<!-- /karni:module:(?P=name) -->\n?",
+    re.DOTALL,
+)
+_H1 = re.compile(r"^# (?P<name>.+?) — agent guidance\s*$")
+_ITEM = re.compile(r"^(?:[-*+]|\d+[.)])\s+")
+_CODE = re.compile(r"""["']code["']\s*:\s*["']P(\d{3})["']""")
+_SIGNATURES = ("This project is built on Karni.", "karni context")
+
+
+@dataclass
+class Migration:
+    entries: list[dict[str, str]] = field(default_factory=list)
+    removed: list[tuple[str, str]] = field(default_factory=list)
+    modules: dict[str, str] = field(default_factory=dict)
+    migrated: list[str] = field(default_factory=list)
+    foreign: list[str] = field(default_factory=list)
+
+
+def _baselines(rel: str, text: str) -> list[str]:
+    """Candidate Karni originals for ``rel`` with the project name filled in."""
+    match = _H1.match(text.splitlines()[0]) if text.strip() else None
+    name = match.group("name") if match else PROJECT_NAME
+    candidates = [LEGACY_FILES[rel]]
+    if rel == "CLAUDE.md":  # pre-AGENTS.md projects kept the full guidance in CLAUDE.md
+        candidates.append(LEGACY_FILES["AGENTS.md"])
+    return [c.replace(PROJECT_NAME, name) for c in candidates]
+
+
+def _ratio(a: list[str], b: list[str]) -> float:
+    return difflib.SequenceMatcher(a=a, b=b, autojunk=False).ratio()
+
+
+def _is_karnis(rel: str, text: str, baseline: str) -> bool:
+    if text == baseline:
+        return True
+    lines, base = text.splitlines(), baseline.splitlines()
+    if _ratio(lines, base) >= SIMILARITY:
+        return True
+    return rel.endswith(".md") and all(sig in text for sig in _SIGNATURES)
+
+
+def _category(heading: str | None) -> str:
+    if not heading:
+        return "project"
+    slug = re.sub(r"[^a-z0-9]+", "-", heading.lower()).strip("-")
+    return f"project-{slug}" if slug else "project"
+
+
+def _group(added: list[tuple[str, str | None]]) -> list[tuple[str, str | None]]:
+    """Fold added lines into entries: one per bullet / numbered item / paragraph.
+
+    A heading the project added becomes the category of what follows it; a
+    heading added with nothing under it is kept as an entry of its own.
+    """
+    entries: list[tuple[str, str | None]] = []
+    current: list[str] = []
+    section: str | None = None
+    headings: list[str] = []
+
+    def flush() -> None:
+        if current:
+            entries.append((" ".join(current), section))
+            current.clear()
+
+    for line, line_section in added:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            flush()
+            if stripped.startswith("#"):
+                headings.append(stripped.lstrip("#").strip())
+            continue
+        if line_section != section:
+            flush()
+            section = line_section
+        if _ITEM.match(stripped):
+            flush()
+            stripped = _ITEM.sub("", stripped, count=1)
+        current.append(stripped)
+    flush()
+    used = {entry_section for _, entry_section in entries}
+    entries += [(f"## {h}", h) for h in headings if h not in used]
+    return entries
+
+
+def _diff(text: str, baseline: str) -> tuple[list[tuple[str, str | None]], list[str]]:
+    """(added lines with their section heading, removed non-blank lines)."""
+    ours, base = text.splitlines(), baseline.splitlines()
+    added: list[tuple[str, str | None]] = []
+    removed: list[str] = []
+    headings: list[str | None] = []
+    heading: str | None = None
+    for line in ours:
+        if line.startswith("## "):
+            heading = line[3:].strip()
+        headings.append(heading)
+    matcher = difflib.SequenceMatcher(a=base, b=ours, autojunk=False)
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag in ("replace", "delete"):
+            removed += [line for line in base[i1:i2] if line.strip()]
+        if tag in ("replace", "insert"):
+            added += [(ours[j], headings[j]) for j in range(j1, j2)]
+    return added, removed
+
+
+def plan(project: Path) -> Migration:
+    migration = Migration()
+    for rel in LEGACY_FILES:
+        path = project / rel
+        if not path.is_file() or is_generated(path):
+            continue
+        text = path.read_text(encoding="utf-8")
+        for block in _MODULE_BLOCK.finditer(text):
+            migration.modules[block.group("name")] = block.group("body").strip() + "\n"
+        text = _MODULE_BLOCK.sub("", text)
+        baselines = _baselines(rel, text)
+        baseline = max(baselines, key=lambda b: _ratio(text.splitlines(), b.splitlines()))
+        if not _is_karnis(rel, text, baseline):
+            migration.foreign.append(rel)
+            continue
+        migration.migrated.append(rel)
+        added, removed = _diff(text.rstrip("\n") + "\n", baseline)
+        prefix = "" if rel in ("AGENTS.md", "CLAUDE.md", ".cursorrules") else f"({rel}) "
+        for statement, heading in _group(added):
+            migration.entries.append(
+                {"rule": prefix + statement, "category": _category(heading), "source": rel}
+            )
+        migration.removed += [(rel, line) for line in removed]
+    return migration
+
+
+def _next_code(existing: str) -> int:
+    used = [int(m) for m in _CODE.findall(existing)]
+    return max(used, default=0) + 1
+
+
+def render_rules_block(migration: Migration, existing: str) -> str:
+    start = _next_code(existing)
+    lines = []
+    if not existing:
+        lines += [
+            '"""Project agent rules for `karni rules` (read statically; literals only).',
+            "",
+            "Schema: ADD / OVERRIDE / DISABLE / ADAPTERS — see docs/agents.md.",
+            '"""',
+            "",
+        ]
+    lines.append("# Migrated by `karni upgrade` from Karni's old agent files (originals in")
+    lines.append("# .karni/backup/). Each entry is text your project added, verbatim.")
+    for rel, line in migration.removed:
+        lines.append(f"# REVIEW: removed from Karni's guidance in {rel}: {line.strip()}")
+    lines.append("ADD += [" if existing else "ADD = [")
+    for offset, entry in enumerate(migration.entries):
+        lines.append("    {")
+        lines.append(f'        "code": "P{start + offset:03d}",')
+        lines.append(f'        "category": {json.dumps(entry["category"], ensure_ascii=False)},')
+        lines.append(f'        "rule": {json.dumps(entry["rule"], ensure_ascii=False)},')
+        lines.append("    },")
+    lines.append("]")
+    return "\n".join(lines) + "\n"
+
+
+def _would_change(migration: Migration) -> list[str]:
+    changed = list(migration.migrated)
+    if migration.entries or migration.removed:
+        changed.append(RULES_FILE)
+    changed += [(MODULES_DIR / f"{name}.md").as_posix() for name in migration.modules]
+    return sorted(set(changed))
+
+
+def _apply(project: Path, migration: Migration) -> list[str]:
+    """Write the migration; returns every file written, backed up or removed."""
+    changed = _would_change(migration)
+    rules_path = project / RULES_FILE
+    existing = rules_path.read_text(encoding="utf-8") if rules_path.is_file() else ""
+    if migration.entries or migration.removed:
+        block = render_rules_block(migration, existing)
+        rules_path.write_text(existing + ("\n" if existing else "") + block, encoding="utf-8")
+    for name, body in migration.modules.items():
+        target = project / MODULES_DIR / f"{name}.md"
+        if not target.is_file():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(body, encoding="utf-8")
+    for rel in migration.migrated:
+        changed.append(backup(project, rel))
+        (project / rel).unlink()
+    result = sync(project, agent_data.load(project))
+    changed += result.written + result.removed
+    return sorted(set(changed))
+
+
+def _notes(migration: Migration) -> list[tuple[str, str]]:
+    """``(file, note)`` for everything a person has to look at."""
+    notes = [
+        (rel, "does not look like Karni's file — left untouched, review it")
+        for rel in migration.foreign
+    ]
+    notes += [
+        (rel, f"REVIEW: you removed {line.strip()!r} (noted in {RULES_FILE})")
+        for rel, line in migration.removed
+    ]
+    return notes
+
+
+def migrate_agent_guidance(project: Path, dry_run: bool) -> list[str]:
+    """Migrate (or, with ``dry_run``, list) the agent files; prints what needs review."""
+    migration = plan(project)
+    for rel, note in _notes(migration):
+        typer.echo(f"   {rel}: {note}")
+    if not migration.migrated:
+        return []
+    if dry_run:
+        return _would_change(migration)
+    return _apply(project, migration)
+
+
+class AgentGuidance(Codemod):
+    """The ``karni upgrade`` codemod: same migration, notes reported as sites."""
+
+    def apply(self, root: Path) -> Outcome:
+        migration = plan(root)
+        sites = [Site(rel, 0, note) for rel, note in _notes(migration)]
+        if not migration.migrated:
+            return Outcome(sites=sites)
+        return Outcome(files=dict.fromkeys(_apply(root, migration), 1), sites=sites)
+
+
+CODEMOD = AgentGuidance()

karni_cli/upgrades/v1_0/__init__.py

@@ -0,0 +1,5 @@
+"""Codemods for changes that break in Karni 1.0: the removals of what 0.2 deprecated.
+
+Every replacement already exists in 0.2, so ``karni upgrade`` runs these
+from 0.2 on, a release before the old names stop working.
+"""

karni_cli/upgrades/v1_0/all_objects_to_without.py

@@ -0,0 +1,18 @@
+"""``Model.all_objects`` -> ``Model.objects.without("soft_delete", reason=...)``.
+
+Changelog entry ``all-objects``; migration note docs/migrations/0.2.md#all_objects.
+"""
+
+from __future__ import annotations
+
+from karni_cli.upgrades.python import ReplaceAttribute
+
+CODEMOD = ReplaceAttribute(
+    attr="all_objects",
+    replacement='objects.without("soft_delete", reason="<auto: migrated from all_objects>")',
+    # all_objects is a manager; the replacement is a queryset. These need the
+    # manager (or would chain a second, conflicting scope lift).
+    manager_only=frozenset(
+        {"get_queryset", "db_manager", "without", "all_with_deleted", "deleted_only"}
+    ),
+)

karni_cli/upgrades/v1_0/all_with_deleted_to_without.py

@@ -0,0 +1,13 @@
+"""``objects.all_with_deleted()`` -> ``objects.without("soft_delete", reason=...)``.
+
+Changelog entry ``all-with-deleted``; migration note docs/migrations/0.2.md#all_with_deleted.
+"""
+
+from __future__ import annotations
+
+from karni_cli.upgrades.python import ReplaceMethodCall
+
+CODEMOD = ReplaceMethodCall(
+    method="all_with_deleted",
+    replacement='without("soft_delete", reason="<auto: migrated from all_with_deleted()>")',
+)

karni_cli/upgrades/v1_0/deleted_only_to_without_dead.py

@@ -0,0 +1,13 @@
+"""``objects.deleted_only()`` -> ``objects.without("soft_delete", reason=...).dead()``.
+
+Changelog entry ``deleted-only``; migration note docs/migrations/0.2.md#deleted_only.
+"""
+
+from __future__ import annotations
+
+from karni_cli.upgrades.python import ReplaceMethodCall
+
+CODEMOD = ReplaceMethodCall(
+    method="deleted_only",
+    replacement='without("soft_delete", reason="<auto: migrated from deleted_only()>").dead()',
+)

karni_cli/upgrades/v1_0/object_permission_classes_to_access.py

@@ -0,0 +1,16 @@
+"""Detector: ``BaseViewSet.object_permission_classes`` -> the ``access`` declaration.
+
+Not mechanical: an arbitrary permission class has no faithful translation
+into access predicates, so this reports every viewset that sets it and edits
+nothing. Changelog entry ``object-permission-classes``; migration note
+docs/migrations/0.2.md#object_permission_classes.
+"""
+
+from __future__ import annotations
+
+from karni_cli.upgrades.python import FindClassAttribute
+
+CODEMOD = FindClassAttribute(
+    name="object_permission_classes",
+    note="express this rule in the access declaration (Owned, HasRole, Where)",
+)

karni_cli/upgrades/v1_0/related_lookups_to_optimize.py

@@ -0,0 +1,15 @@
+"""Detector: ``karni.api.expansion.related_lookups()`` -> ``karni.api.optimizer.optimize()``.
+
+Not mechanical: the replacement takes a queryset and a serializer instead
+of expand paths. Changelog entry ``related-lookups``; migration note
+docs/migrations/0.2.md#related_lookups-and-scoped_related_lookups.
+"""
+
+from __future__ import annotations
+
+from karni_cli.upgrades.python import FindReferences
+
+CODEMOD = FindReferences(
+    qualified_names=("karni.api.expansion.related_lookups",),
+    note="replace with karni.api.optimizer.optimize(queryset, serializer)",
+)

karni_cli/upgrades/v1_0/scoped_related_lookups_to_optimize.py

@@ -0,0 +1,15 @@
+"""Detector: ``karni.api.expansion.scoped_related_lookups()`` -> ``optimize(..., scope=...)``.
+
+Not mechanical: the replacement takes a queryset and a serializer instead
+of expand paths. Changelog entry ``scoped-related-lookups``; migration note
+docs/migrations/0.2.md#related_lookups-and-scoped_related_lookups.
+"""
+
+from __future__ import annotations
+
+from karni_cli.upgrades.python import FindReferences
+
+CODEMOD = FindReferences(
+    qualified_names=("karni.api.expansion.scoped_related_lookups",),
+    note="replace with karni.api.optimizer.optimize(queryset, serializer, scope=...)",
+)

karni_cli/upgrades/v1_0/soft_delete_manager_mixin_to_scoped.py

@@ -0,0 +1,14 @@
+"""``karni.managers.SoftDeleteManagerMixin`` -> ``karni.managers.ScopedManagerMixin``.
+
+Changelog entry ``soft-delete-manager-mixin``; migration note
+docs/migrations/0.2.md#softdeletemanagermixin.
+"""
+
+from __future__ import annotations
+
+from karni_cli.upgrades.python import RenameSymbol
+
+CODEMOD = RenameSymbol(
+    old="karni.managers.SoftDeleteManagerMixin",
+    new="karni.managers.ScopedManagerMixin",
+)