karni-cli 0.3.1__py3-none-any.whl

karni_cli/_changelog/0.2.0.toml

@@ -0,0 +1,304 @@
+# Karni 0.2.0: breaking changes and deprecations since 0.1.0.
+# Schema and rules: karni/changelog/__init__.py. Migration notes: docs/migrations/0.2.md.
+# `karni upgrade` runs each codemod (karni_cli/upgrades/<codemod>.py) in order and
+# reports every manual change with its migration note.
+version = "0.2.0"
+
+# --- deprecated in 0.2, removed in 1.0 ------------------------------------------
+
+[[change]]
+id = "all-objects"
+kind = "api-change"
+symbol = "Model.all_objects"
+replacement = 'Model.objects.without("soft_delete", reason=...)'
+summary = """\
+The all_objects manager is replaced by lifting the soft_delete scope by name. \
+Until 1.0 it still works, but it now lifts only soft_delete (it used to drop \
+every default-manager filter)."""
+removed_in = "1.0"
+mechanical = true
+codemod = "v1_0.all_objects_to_without"
+migration = "migrations/0.2.md#all_objects"
+
+[[change]]
+id = "all-with-deleted"
+kind = "api-change"
+symbol = "objects.all_with_deleted()"
+replacement = 'objects.without("soft_delete", reason=...)'
+summary = "The manager method is replaced by lifting the soft_delete scope by name."
+removed_in = "1.0"
+mechanical = true
+codemod = "v1_0.all_with_deleted_to_without"
+migration = "migrations/0.2.md#all_with_deleted"
+
+[[change]]
+id = "deleted-only"
+kind = "api-change"
+symbol = "objects.deleted_only()"
+replacement = 'objects.without("soft_delete", reason=...).dead()'
+summary = "The manager method is replaced by lifting soft_delete and keeping only dead rows."
+removed_in = "1.0"
+mechanical = true
+codemod = "v1_0.deleted_only_to_without_dead"
+migration = "migrations/0.2.md#deleted_only"
+
+[[change]]
+id = "soft-delete-manager-mixin"
+kind = "base-rename"
+symbol = "karni.managers.SoftDeleteManagerMixin"
+replacement = "karni.managers.ScopedManagerMixin"
+summary = """\
+The manager mixin runs every named scope now, not just soft delete, so it was \
+renamed. The old name is the same class."""
+removed_in = "1.0"
+mechanical = true
+codemod = "v1_0.soft_delete_manager_mixin_to_scoped"
+migration = "migrations/0.2.md#softdeletemanagermixin"
+
+[[change]]
+id = "object-permission-classes"
+kind = "api-change"
+symbol = "BaseViewSet.object_permission_classes"
+replacement = "the access declaration (access = Access(read=..., write=...))"
+summary = """\
+Object-level permission classes on a BaseViewSet are replaced by the access \
+declaration. They still run, after the access object check, until 1.0. The \
+rule they encode has to be re-expressed as access predicates by hand."""
+removed_in = "1.0"
+mechanical = false
+codemod = "v1_0.object_permission_classes_to_access"
+migration = "migrations/0.2.md#object_permission_classes"
+
+[[change]]
+id = "related-lookups"
+kind = "api-change"
+symbol = "karni.api.expansion.related_lookups"
+replacement = "karni.api.optimizer.optimize(queryset, serializer, scope=...)"
+summary = """\
+The expansion-only lookup helper is subsumed by the serializer-walking query \
+optimiser, which takes a queryset and a serializer instead of expand paths."""
+removed_in = "1.0"
+mechanical = false
+codemod = "v1_0.related_lookups_to_optimize"
+migration = "migrations/0.2.md#related_lookups-and-scoped_related_lookups"
+
+[[change]]
+id = "scoped-related-lookups"
+kind = "api-change"
+symbol = "karni.api.expansion.scoped_related_lookups"
+replacement = "karni.api.optimizer.optimize(queryset, serializer, scope=...)"
+summary = """\
+The scoped expansion lookup helper is subsumed by the query optimiser, which \
+applies each target viewset's read scope itself."""
+removed_in = "1.0"
+mechanical = false
+codemod = "v1_0.scoped_related_lookups_to_optimize"
+migration = "migrations/0.2.md#related_lookups-and-scoped_related_lookups"
+
+# --- breaking in 0.2 -----------------------------------------------------------
+
+[[change]]
+id = "agent-guidance-files"
+kind = "project-files"
+symbol = "AGENTS.md, CLAUDE.md, .cursorrules, .claude/commands/*.md"
+replacement = "karni.rules.py plus adapters generated by `karni rules sync`"
+summary = """\
+Hand-written agent guidance files became generated adapters. The project's own \
+additions move to karni.rules.py verbatim, module blocks to .karni/modules/, and \
+the originals are backed up under .karni/backup/."""
+mechanical = true
+codemod = "v0_2.agent_guidance"
+migration = "migrations/0.2.md#agent-guidance-files"
+
+[[change]]
+id = "mandatory-access"
+kind = "behaviour"
+symbol = "karni.api.BaseViewSet"
+replacement = 'access = Access(read=..., write=...) or access = Unscoped(reason="...")'
+summary = """\
+Every BaseViewSet must declare access. A viewset without one fails `karni check` \
+(viewset-access) and denies every request at runtime. An object outside the read \
+scope answers 404; one readable but not writable answers 403."""
+mechanical = false
+migration = "migrations/0.2.md#every-baseviewset-declares-access"
+
+[[change]]
+id = "default-permission-classes"
+kind = "behaviour"
+symbol = 'REST_FRAMEWORK["DEFAULT_PERMISSION_CLASSES"]'
+replacement = "rest_framework.permissions.IsAuthenticated"
+summary = """\
+Karni's default changed from IsAuthenticatedOrReadOnly to IsAuthenticated, and \
+it no longer gates a BaseViewSet with an access declaration. It still covers \
+plain DRF views and Unscoped viewsets, which no longer allow anonymous reads."""
+mechanical = false
+migration = "migrations/0.2.md#default_permission_classes"
+
+[[change]]
+id = "relation-read-scope"
+kind = "behaviour"
+symbol = "relation fields and ?expand="
+summary = """\
+A writable relation field accepts only primary keys the requester can read \
+through the target model's viewset, and ?expand= embeds only readable rows (an \
+unreadable to-one target renders as null)."""
+mechanical = false
+migration = "migrations/0.2.md#relations-and-expansion-follow-the-targets-read-scope"
+
+[[change]]
+id = "max-page-size"
+kind = "behaviour"
+symbol = "KarniPageNumberPagination.max_page_size"
+replacement = "KARNI_MAX_PAGE_SIZE"
+summary = """\
+?page_size= is capped at KARNI_MAX_PAGE_SIZE, default 100 (was a hard-coded \
+500). A paginator subclass may lower the cap, never raise it."""
+mechanical = false
+migration = "migrations/0.2.md#karni_max_page_size-defaults-to-100"
+
+[[change]]
+id = "pagination-required"
+kind = "behaviour"
+symbol = "pagination_class = None"
+replacement = 'pagination = Unpaginated(max_rows=..., reason="...")'
+summary = """\
+pagination_class = None on a BaseViewSet is a class-definition error, and boot \
+refuses REST_FRAMEWORK["PAGE_SIZE"] = None or a non-Karni default pagination \
+class. An unpaginated list is declared with Unpaginated(...)."""
+mechanical = false
+migration = "migrations/0.2.md#unpaginated-lists-need-unpaginated"
+
+[[change]]
+id = "query-budgets"
+kind = "behaviour"
+symbol = "KARNI_QUERY_BUDGET_MODE"
+replacement = 'query_budget = Budget(list=..., reason="...") on the viewset'
+summary = """\
+Every list, retrieve, create, update and destroy has a query budget. Karni's \
+pytest plugin runs tests with KARNI_QUERY_BUDGET_MODE = "raise", so an action \
+over budget now fails its test."""
+mechanical = false
+migration = "migrations/0.2.md#query-budgets-fail-tests"
+
+[[change]]
+id = "roles-as-data"
+kind = "behaviour"
+symbol = "KARNI_ROLES and migrate"
+replacement = "KARNI_ROLES = {...}; karni sync-roles"
+summary = """\
+Roles are data (ADR 0002): migrate now creates the roles KARNI_ROLES declares \
+(staff, user and customer by default, as groups plus Role rows with grants) and \
+a Role row for every existing group. Nothing is deleted; Can('app.model:action') \
+is available in access declarations."""
+mechanical = false
+migration = "migrations/0.2.md#roles-as-data"
+
+[[change]]
+id = "row-level-scoping"
+kind = "behaviour"
+symbol = "admin row scope"
+replacement = 'access = Granted(); scope_exempt = True, scope_exempt_reason = "..."'
+summary = """\
+Row-level scoping (ADR 0002, P2): access = Granted() scopes a viewset by the \
+roles' grants and is what karni make viewset writes, and the admin now shows \
+only the rows the user's grants reach — a staff user with Django permissions \
+but no grant sees nothing. scope_exempt opts a viewset or admin out, with a \
+reason that karni check lists."""
+mechanical = false
+migration = "migrations/0.2.md#row-level-scoping"
+
+[[change]]
+id = "field-visibility"
+kind = "behaviour"
+symbol = 'ordering_fields = "__all__"'
+replacement = "class Karni: field_roles = {...} on the model; ordering_fields on a viewset that needs more"
+summary = """\
+Field-level visibility (ADR 0002, P3): Karni.field_roles hides fields per role on \
+the API, in ?expand=, in the schema and in the admin. ?ordering= now accepts only \
+the fields the request's serializer reads back (write-only and hidden fields no \
+longer order the list), and search_fields may not name a write-only field \
+(karni.E131)."""
+mechanical = false
+migration = "migrations/0.2.md#field-level-visibility"
+
+[[change]]
+id = "change-history"
+kind = "behaviour"
+symbol = "karni.audit"
+replacement = "class Karni: audit = True on the models to record"
+summary = """\
+Change history (ADR 0002, P4): the new karni.audit app (run migrate once) records \
+field-level diffs for models that opt in, surfaced on the admin History tab, \
+GET /<resource>/<id>/history/ and <ChangeHistory/>; QuerySet.update()/bulk_update() \
+on an audited model is flagged by karni check (audited-bulk-write)."""
+mechanical = false
+migration = "migrations/0.2.md#change-history"
+
+[[change]]
+id = "permission-matrix"
+kind = "behaviour"
+symbol = "karni.accounts.matrix"
+replacement = "the Permission matrix admin page / POST api/auth/permissions/matrix/"
+summary = """\
+Permission matrix (ADR 0002, P5): grants change in the admin (Roles → Permission \
+matrix) or through api/auth/permissions/matrix/ with guard rails and a confirmation \
+diff, and every change is history. RolePermission gains `origin` (run migrate once); \
+a grant set in the matrix is kept by karni sync-roles and reported as overridden; a \
+revoked declared grant stays as a `none` row. Dropped declared grants are now removed \
+outright instead of soft-deleted."""
+mechanical = false
+migration = "migrations/0.2.md#permission-matrix"
+
+[[change]]
+id = "import-export"
+kind = "behaviour"
+symbol = "karni.transfer"
+replacement = "GET /<resource>/export/, /<resource>/import/…, the admin's Export/Import, <ResourceImport/>"
+summary = """\
+Import and export (ADR 0002, P6): the new karni.transfer app (run migrate once; \
+karni.audit gains ChangeBatch) gives every BaseViewSet a CSV/XLSX export of the \
+list as the request sees it and a four-step import with a mandatory dry run, \
+audited as one batch; every Karni admin gains the export actions and an import \
+page; @karni/ui gains <ResourceImport/> and export buttons on <ResourceTable>; \
+openpyxl is a new core dependency."""
+mechanical = false
+migration = "migrations/0.2.md#import-and-export"
+
+[[change]]
+id = "write-interception"
+kind = "behaviour"
+symbol = "karni.signals.pre_write"
+replacement = "nothing: an additive hook (karni-approvals is its first user)"
+summary = """\
+Every BaseModel save() and delete() now sends karni.signals.pre_write first; a \
+receiver raising KarniWriteDeferred stops the write before any SQL (the API answers \
+202 with its payload, the admin shows its message). Code that wraps model saves \
+in its own transactions sees no difference; a custom BaseModel.save() override \
+must call super().save() for the hook to fire."""
+mechanical = false
+migration = "migrations/0.2.md#write-interception"
+
+[[change]]
+id = "architecture-scans-without-base-dir"
+kind = "behaviour"
+symbol = "BASE_DIR"
+replacement = "nothing: discovery infers the project root"
+summary = """\
+karni check and the architecture suite now scan the project's apps without \
+settings.BASE_DIR (they infer the root from the settings package); projects \
+that scanned nothing before may see violations on the next karni check."""
+mechanical = false
+migration = "migrations/0.2.md#architecture-rules-scan-the-project-without-base_dir"
+
+[[change]]
+id = "vetoes"
+kind = "behaviour"
+symbol = "karni.vetoes"
+replacement = "call super() (or self.vetoed(request, action)) in admin permission overrides"
+summary = """\
+The API gate and the admin consult karni.vetoes after the access declaration \
+admitted an action. Nothing changes without a registered veto; a Karni admin \
+that overrides has_delete_permission or get_actions without super() skips the \
+check there."""
+mechanical = false
+migration = "migrations/0.2.md#vetoes-at-the-gates"

karni_cli/_changelog/0.3.0.toml

@@ -0,0 +1,25 @@
+# Karni 0.3.0: breaking changes since 0.2.0.
+# Schema and rules: karni/changelog/__init__.py. Migration notes: docs/migrations/0.3.md.
+# Neither change has a codemod: both are reported by `karni upgrade` with their note.
+version = "0.3.0"
+
+[[change]]
+id = "django-5-2"
+kind = "behaviour"
+symbol = "Django"
+summary = """\
+Karni requires Django 5.2 LTS (>=5.2.8). Django 5.1 is out of support with \
+unpatched security advisories, and its admin fails on Python 3.14."""
+mechanical = false
+migration = "migrations/0.3.md#django-52-lts"
+
+[[change]]
+id = "role-scope-paths-checked"
+kind = "behaviour"
+symbol = "KARNI_ROLES"
+summary = """\
+Every path a role's grants filter on is resolved at startup. A path that does \
+not resolve on its model is now system check error karni.E214 instead of a 500 \
+on the first request that uses it."""
+mechanical = false
+migration = "migrations/0.3.md#role-scope-paths-are-checked-at-startup"

karni_cli/_changelog/__init__.py

@@ -0,0 +1,248 @@
+"""Karni's machine-readable changelog: every breaking change and deprecation, per release.
+
+``karni upgrade`` (karni-cli) reads it to find every change between a
+project's Karni version and the target, runs their codemods in order and
+reports what it could not fix. ``docs/migrations/<version>.md`` explains each
+entry for humans. This package is stdlib only: karni-cli loads it by path
+(bundled as ``karni_cli/_changelog``) without importing Django or Karni.
+
+One TOML file per release, named by its version (``0.2.0.toml``). A release
+only ever adds its own file; entries are never edited after they ship. Schema::
+
+    version = "0.2.0"                 # must match the file name
+
+    [[change]]
+    id = "all-objects"                # unique across every release, kebab-case
+    kind = "api-change"               # one of KINDS
+    symbol = "Model.all_objects"      # what changed: dotted path, setting, method, file
+    replacement = 'Model.objects.without("soft_delete", reason=...)'  # required for renames
+    summary = "One or two sentences: what changed and what breaks."
+    removed_in = "1.0"                # deprecations only: the release that removes `symbol`
+    mechanical = true                 # a codemod rewrites every use safely
+    codemod = "v1_0.all_objects_to_without"   # module under karni_cli.upgrades
+    migration = "migrations/0.2.md#all_objects"  # migration note, relative to docs/
+
+A change *breaks* at ``removed_in`` when set (a deprecation: the old name
+keeps working, with a :class:`karni.deprecation.KarniDeprecationWarning`,
+from ``version`` until then), else at ``version`` itself. ``mechanical = true``
+requires ``codemod``. A manual change (``mechanical = false``) may still name
+one: a detector that reports the code to change without editing it.
+
+Override / escape hatch: :func:`load` takes any directory, so tools and tests
+can read another changelog with the same schema and validation.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Final
+
+from karni import links as _links
+
+__all__ = [
+    "DOCS_BASE_URL",
+    "KINDS",
+    "Change",
+    "ChangelogError",
+    "Release",
+    "changes",
+    "docs_url",
+    "load",
+    "version_key",
+]
+
+#: Where ``docs/`` is published: ``migration`` values here and ``doc_anchor``
+#: values in :func:`karni.deprecation.warn_deprecated` are relative to it.
+#: Set in one place, ``karni.links``; re-exported here for the upgrade tooling.
+DOCS_BASE_URL: Final[str] = _links.DOCS_BASE_URL
+
+#: What a change can be. ``project-files``: files the scaffold generated changed shape.
+KINDS: Final = (
+    "setting-rename",
+    "import-move",
+    "base-rename",
+    "api-change",
+    "behaviour",
+    "project-files",
+)
+#: Kinds whose ``replacement`` is a name a codemod renames ``symbol`` to.
+RENAME_KINDS: Final = frozenset({"setting-rename", "import-move", "base-rename"})
+
+DIRECTORY: Final = Path(__file__).resolve().parent
+
+_ID = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_VERSION = re.compile(r"^\d+(?:\.\d+){0,2}$")
+_CODEMOD = re.compile(r"^v\d+_\d+\.[a-z_][a-z0-9_]*$")
+_MIGRATION = re.compile(r"^migrations/[\w.-]+\.md#[\w-]+$")
+_REQUIRED: Final = ("id", "kind", "symbol", "summary", "mechanical", "migration")
+_OPTIONAL: Final = ("replacement", "removed_in", "codemod")
+
+
+def docs_url(doc_anchor: str) -> str:
+    """Absolute docs-site link for ``doc_anchor`` (``"migrations/0.2.md#section"``).
+
+    Pages are addressed as in the repository (``models.md``); the site serves
+    each page as a directory (``models/``), so the link is translated.
+    """
+    path, _, anchor = doc_anchor.lstrip("/").partition("#")
+    if path.endswith(".md"):
+        path = path[:-3]
+        path = "" if path == "index" else path + "/"
+    return DOCS_BASE_URL + path + (f"#{anchor}" if anchor else "")
+
+
+class ChangelogError(ValueError):
+    """The changelog does not match the schema (the message lists every problem).
+
+    Code ``E704``; a ``ValueError`` so callers that predate the code keep working.
+    """
+
+    code = "E704"
+
+    def __str__(self) -> str:
+        return f"{self.code}: {super().__str__()} See {DOCS_BASE_URL}errors/#e704"
+
+
+def version_key(text: str) -> tuple[int, int, int]:
+    """``"1.0"`` -> ``(1, 0, 0)``: release versions only (``MAJOR[.MINOR[.PATCH]]``)."""
+    if not _VERSION.match(text):
+        raise ChangelogError(f"{text!r} is not a release version (MAJOR[.MINOR[.PATCH]])")
+    major, minor, patch = ([int(part) for part in text.split(".")] + [0, 0])[:3]
+    return major, minor, patch
+
+
+@dataclass(frozen=True)
+class Change:
+    """One breaking change or deprecation."""
+
+    id: str
+    release: str
+    kind: str
+    symbol: str
+    summary: str
+    mechanical: bool
+    migration: str
+    replacement: str = ""
+    removed_in: str = ""
+    codemod: str = ""
+
+    @property
+    def breaks_in(self) -> str:
+        """The release whose code no longer accepts the old form."""
+        return self.removed_in or self.release
+
+    @property
+    def is_deprecation(self) -> bool:
+        return bool(self.removed_in)
+
+
+@dataclass(frozen=True)
+class Release:
+    version: str
+    changes: tuple[Change, ...]
+
+
+def _change(raw: Any, release: str, where: str, problems: list[str]) -> Change | None:
+    if not isinstance(raw, dict):
+        problems.append(f"{where}: a [[change]] must be a table")
+        return None
+    label = f"{where} ({raw.get('id', '?')})"
+    missing = [key for key in _REQUIRED if key not in raw]
+    unknown = sorted(set(raw) - set(_REQUIRED) - set(_OPTIONAL))
+    if missing:
+        problems.append(f"{label}: missing {', '.join(missing)}")
+    if unknown:
+        problems.append(f"{label}: unknown key(s) {', '.join(unknown)}")
+    if missing or unknown:
+        return None
+    for key in (*_REQUIRED, *_OPTIONAL):
+        if key in raw and key != "mechanical" and not isinstance(raw[key], str):
+            problems.append(f"{label}: {key} must be a string")
+            return None
+    if not isinstance(raw["mechanical"], bool):
+        problems.append(f"{label}: mechanical must be true or false")
+        return None
+    change = Change(release=release, **raw)
+    if not _ID.match(change.id):
+        problems.append(f"{label}: id must be kebab-case")
+    if change.kind not in KINDS:
+        problems.append(f"{label}: kind {change.kind!r} is not one of {', '.join(KINDS)}")
+    if not change.summary.strip() or not change.symbol.strip():
+        problems.append(f"{label}: symbol and summary must not be empty")
+    if change.kind in RENAME_KINDS and not change.replacement:
+        problems.append(f"{label}: a {change.kind} needs a replacement")
+    if change.removed_in:
+        try:
+            if version_key(change.removed_in) <= version_key(release):
+                problems.append(f"{label}: removed_in must be later than {release}")
+        except ChangelogError as exc:
+            problems.append(f"{label}: removed_in: {exc}")
+    if change.mechanical and not change.codemod:
+        problems.append(f"{label}: a mechanical change needs a codemod")
+    if change.codemod and not _CODEMOD.match(change.codemod):
+        problems.append(f"{label}: codemod must look like 'v1_0.module_name'")
+    if not _MIGRATION.match(change.migration):
+        problems.append(f"{label}: migration must look like 'migrations/<file>.md#<anchor>'")
+    return change
+
+
+def _release(path: Path, problems: list[str]) -> Release | None:
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        problems.append(f"{path.name}: invalid TOML: {exc}")
+        return None
+    version = data.get("version")
+    if version != path.stem:
+        problems.append(f"{path.name}: version = {version!r} must match the file name")
+        return None
+    try:
+        version_key(version)
+    except ChangelogError as exc:
+        problems.append(f"{path.name}: {exc}")
+        return None
+    unknown = sorted(set(data) - {"version", "change"})
+    if unknown:
+        problems.append(f"{path.name}: unknown key(s) {', '.join(unknown)}")
+    raw_changes = data.get("change", [])
+    if not isinstance(raw_changes, list):
+        problems.append(f"{path.name}: change must be an array of tables ([[change]])")
+        return None
+    parsed = [
+        _change(raw, version, f"{path.name}[{index}]", problems)
+        for index, raw in enumerate(raw_changes)
+    ]
+    return Release(version, tuple(change for change in parsed if change is not None))
+
+
+def load(directory: Path | None = None) -> tuple[Release, ...]:
+    """Every release in ``directory`` (default: Karni's own), oldest first.
+
+    :raises ChangelogError: listing every schema problem found.
+    """
+    root = DIRECTORY if directory is None else directory
+    problems: list[str] = []
+    releases = [
+        release
+        for path in sorted(root.glob("*.toml"))
+        if (release := _release(path, problems)) is not None
+    ]
+    seen: dict[str, str] = {}
+    for release in releases:
+        for change in release.changes:
+            if change.id in seen:
+                problems.append(
+                    f"duplicate id {change.id!r} in {seen[change.id]} and {release.version}"
+                )
+            seen[change.id] = release.version
+    if problems:
+        raise ChangelogError("invalid changelog:\n  " + "\n  ".join(problems))
+    return tuple(sorted(releases, key=lambda release: version_key(release.version)))
+
+
+def changes(directory: Path | None = None) -> list[Change]:
+    """Every change, oldest release first, in file order within a release."""
+    return [change for release in load(directory) for change in release.changes]