karni-cli 0.3.1__py3-none-any.whl

karni_cli/generators/apitest.py

@@ -0,0 +1,206 @@
+"""``karni make test <Model>`` — the resource's API test: full CRUD surface plus isolation.
+
+Writes ``<app>/tests/test_<model>.py`` with a :class:`karni.testing.APITestCase`
+that calls ``assert_crud`` (list, retrieve, create, update, delete, the
+promised denials, pagination, filtering and the OpenAPI contract, in one
+call) and — when the viewset's ``access`` reads through ``Owned(...)``, or
+through ``Granted()`` with a role whose grant is ``own`` / ``related`` —
+``assert_isolated`` (another scope's rows are out of reach). The role is
+``--role``, else the first ``HasRole("...")`` the viewset declares, else for
+``Granted()`` the first role in ``KARNI_ROLES`` (the shipped ``user`` when
+the project declares none) whose grants reach the model, else any signed-in
+user. The model needs a viewset first (``karni make viewset``).
+"""
+
+from __future__ import annotations
+
+import textwrap
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.introspect import (
+    ModelInfo,
+    declared_roles,
+    grant_scopes,
+    granted_reads,
+    owned_paths,
+    require_model,
+    role_names,
+    viewset_for,
+    viewset_module,
+)
+from karni_cli.generators.naming import require_pascal, snake
+from karni_cli.generators.pysource import Import, docstring, ensure_imports, pystr
+from karni_cli.project import CliError
+
+NAME = "test"
+SUMMARY = "Add <app>/tests/test_<model>.py: assert_crud + the isolation check for a resource."
+
+
+def render(
+    ws: Workspace,
+    model: str,
+    viewset: str,
+    module: str,
+    role: str | None,
+    isolation: bool,
+    note: str | None = None,
+) -> str:
+    """The test module's text (ruff-clean in the project's layout)."""
+    rel = "tests/test.py"
+    line = ws.line_length
+    role_arg = f", {pystr(role)}" if role else ""
+    lines = [
+        docstring(
+            f"The {model} API: CRUD, access" + (" and isolation" if isolation else "") + ".",
+            "",
+            line,
+        ),
+        "",
+        "",
+        f"class {model}APITests(APITestCase):",
+        "    def test_crud(self) -> None:",
+        f"        self.assert_crud({viewset}{role_arg})",
+    ]
+    if isolation:
+        lines += [
+            "",
+            "    def test_owners_cannot_reach_each_others_rows(self) -> None:",
+            f"        self.assert_isolated({viewset}{role_arg})",
+        ]
+    elif note:
+        wrapped = textwrap.wrap(f"No assert_isolated: {note}", width=max(line - 6, 40))
+        lines += ["", *(f"    # {part}" for part in wrapped)]
+    text = "\n".join(lines) + "\n"
+    return ensure_imports(
+        ws, rel, text, [Import("karni.testing", "APITestCase"), Import(module, viewset)]
+    )
+
+
+def _scoped(scope: str | None) -> bool:
+    return scope is not None and (scope == "own" or scope.startswith("related:"))
+
+
+def no_isolation_reason(ws: Workspace, model: ModelInfo, *, explicit: bool) -> str | None:
+    """Why no ``assert_isolated`` is written, when a reader would expect one; else ``None``.
+
+    Never silent: a role reaching the rows through a ``custom:`` scope is
+    always named (``assert_isolated`` cannot drive one); with the role picked
+    automatically, a resource no role partitions is named too. An explicit
+    ``--role`` whose grant is ``all`` is the caller's choice and says nothing.
+    """
+    key = f"{model.app.label}.{model.name.lower()}:view"
+    scopes = grant_scopes(declared_roles(ws), key)
+    custom = sorted(
+        f"{slug!r} ({scope})" for slug, scope in scopes.items() if scope.startswith("custom:")
+    )
+    if custom:
+        return (
+            f"{', '.join(custom)} reach {key} through a custom scope, which assert_isolated "
+            "cannot drive. For membership, grant 'own' with `class Karni: owner_field = "
+            "'<path to the user>'` (e.g. 'workspace__members') and regenerate this test."
+        )
+    if not explicit and scopes:
+        return (
+            f"no role's grant on {key} is 'own' or 'related:<key>', so every role that reads "
+            f"{model.name} sees every row. If rows belong to someone, declare "
+            "`class Karni: owner_field` and grant 'own'."
+        )
+    return None
+
+
+def granted_role(ws: Workspace, model: ModelInfo, role: str | None) -> tuple[str | None, bool]:
+    """``(role, isolates)`` for a ``Granted()`` viewset of ``model``.
+
+    ``role`` when given; else the first role in ``KARNI_ROLES`` whose grant
+    for the model's ``view`` permission is ``own`` / ``related`` (so the
+    isolation check applies), else the first whose grants reach it at all.
+    ``isolates`` says whether that role's grant partitions the rows.
+    """
+    key = f"{model.app.label}.{model.name.lower()}:view"
+    scopes = grant_scopes(declared_roles(ws), key)
+    if role is not None:
+        return role, _scoped(scopes.get(role))
+    for slug, scope in scopes.items():
+        if _scoped(scope):
+            return slug, True
+    if scopes:
+        return next(iter(scopes)), False
+    return None, False
+
+
+def plan(ws: Workspace, app: App, model_name: str, *, role: str | None = None) -> str:
+    """Plan the test module for ``model_name``; returns its path relative to the project."""
+    model = require_model(ws, app, require_pascal(model_name, "Model"))
+    found = viewset_for(ws, model.app, model.name)
+    if found is None:
+        raise CliError(
+            f"No viewset routes {model.name} — create it first: karni make viewset "
+            f"{model.name} --app {model.app.label} (the test drives the resource's URLs).",
+            code="C105",
+        )
+    path, cls = found
+    roles = role_names(cls)
+    chosen = role if role is not None else (roles[0] if roles else None)
+    owned = bool(owned_paths(cls))
+    granted = not owned and granted_reads(cls)
+    how = " + owner isolation" if owned else ""
+    note: str | None = None
+    if granted and chosen is None or granted and role is not None:
+        chosen, scoped = granted_role(ws, model, role)
+        how = " + grant isolation" if scoped else ""
+        if not scoped:
+            note = no_isolation_reason(ws, model, explicit=role is not None)
+        if chosen is None:
+            ws.note(
+                f"no role in KARNI_ROLES grants {model.app.label}.{model.name.lower()}:view; "
+                "as any signed-in user the test is refused everything — pass --role"
+            )
+    module = viewset_module(ws, model.app, path)
+    tests = model.app.file("tests")
+    init = tests / "__init__.py"
+    if not ws.exists(init):
+        ws.create(init, "")
+    target = tests / f"test_{snake(model.name)}.py"
+    ws.create(target, render(ws, model.name, cls.name, module, chosen, bool(how), note))
+    who = f"role {chosen!r}" if chosen else "any signed-in user"
+    ws.note(f"test: {cls.name} as {who}{how}")
+    if note:
+        ws.note(f"isolation: NOT generated — {note}")
+    ws.note(f"run: karni test {ws.rel(target)}")
+    return ws.rel(target)
+
+
+def command(
+    model: str = typer.Argument(..., help="Model class name (e.g. Event); it needs a viewset."),
+    role: str | None = typer.Option(
+        None,
+        "--role",
+        help="The role the test acts as. Default: the first HasRole the viewset declares; "
+        "for Granted() the first KARNI_ROLES role whose grant reaches the model (own/related "
+        "first); else any signed-in user.",
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add APP/tests/test_<model>.py — the resource's whole API surface in a few lines.
+
+    One APITestCase: `assert_crud` checks list, retrieve, create, update,
+    delete, the denials the access declaration promises, pagination,
+    filtering and the OpenAPI contract; `assert_isolated` (when reads are
+    Owned, or Granted() with an own/related grant) checks another scope's
+    rows are out of reach on every surface. Run it with `karni test`.
+    """
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), model, role=role)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/app.py

@@ -0,0 +1,103 @@
+"""``karni make app <name>`` — a local Django app, wired into ``# karni:apps``.
+
+Replaces ``manage.py startapp``: only ``models.py`` and ``viewsets.py`` (plus
+``apps.py``, ``migrations/`` and ``tests/``) — no admin.py, serializers.py or
+urls.py, which Karni derives.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from karni_cli.generators.core import (
+    DRY_RUN_OPTION,
+    SETTINGS,
+    Workspace,
+    project_workspace,
+    require_settings,
+)
+from karni_cli.generators.naming import pascal, require_snake
+from karni_cli.generators.pysource import docstring
+from karni_cli.project import CliError
+from karni_cli.settings_edit import MARKER, add_entry
+
+NAME = "app"
+SUMMARY = "Create a local Django app (models.py, viewsets.py) wired into # karni:apps."
+
+#: Top-level names a project already uses, or that would shadow a dependency.
+_TAKEN = frozenset(
+    {"config", "frontend", "tests", "modules", "manage", "karni", "django", "rest_framework"}
+)
+
+
+def plan(ws: Workspace, name: str) -> str:
+    """Plan the app ``name``; returns its label."""
+    require_snake(name, "App name")
+    if name in _TAKEN or name in sys.stdlib_module_names:
+        raise CliError(
+            f"App name {name!r} would shadow an existing module — choose another.", code="C103"
+        )
+    if name.startswith("karni_"):
+        raise CliError(
+            f"App name {name!r}: karni_* names belong to Karni modules — use "
+            "`karni make module` for a reusable module, or drop the prefix.",
+            code="C103",
+        )
+    settings = require_settings(ws)
+    root = ws.path(name)
+    if ws.exists(ws.path(f"{name}.py")):
+        raise CliError(
+            f"{name}.py exists in the project root — an app {name}/ would clash.", code="C103"
+        )
+    line = ws.line_length
+    files = {
+        "__init__.py": "",
+        "apps.py": (
+            "from django.apps import AppConfig\n\n\n"
+            f"class {pascal(name)}Config(AppConfig):\n"
+            '    default_auto_field = "django.db.models.BigAutoField"\n'
+            f'    name = "{name}"\n'
+        ),
+        "models.py": docstring(
+            f"{name} models, each on karni.models.BaseModel: `karni make model <Name>`.", "", line
+        )
+        + "\n",
+        "viewsets.py": docstring(
+            f"{name} API: BaseViewSet subclasses, auto-routed: `karni make viewset <Model>`.",
+            "",
+            line,
+        )
+        + "\n",
+        "migrations/__init__.py": "",
+        "tests/__init__.py": "",
+    }
+    ws.create_skeleton({root / rel: content for rel, content in files.items()})
+    updated = add_entry(
+        settings, name, setting="INSTALLED_APPS", marker=MARKER, filename=SETTINGS.as_posix()
+    )
+    if updated is not None:
+        ws.write(SETTINGS, updated)
+    ws.note(f"next: karni make model <Name> [field:type ...] --app {name}")
+    return name
+
+
+def command(
+    name: str = typer.Argument(..., help="App label, snake_case (e.g. events)."),
+    force: bool = typer.Option(
+        False, "--force", help="Create only the missing files of an existing app (keeps the rest)."
+    ),
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Create a local app — replaces `manage.py startapp`.
+
+    Writes NAME/{__init__,apps,models,viewsets}.py, NAME/migrations/ and
+    NAME/tests/, and adds NAME to the `# karni:apps` block of
+    config/settings.py. No admin.py, serializers.py or urls.py: Karni derives
+    them. An existing app is never truncated: --force only fills in missing
+    files.
+    """
+    ws = project_workspace(force)
+    plan(ws, name)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/command.py

@@ -0,0 +1,98 @@
+"""``karni make command <name>`` — a management command in ``<app>/management/commands/``.
+
+Run it with ``karni manage <name>`` (through the project interpreter).
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+)
+from karni_cli.generators.naming import humanize, require_snake
+from karni_cli.generators.pysource import pystr
+from karni_cli.project import CliError
+
+NAME = "command"
+SUMMARY = "Add a management command (<app>/management/commands/<name>.py)."
+
+#: Django's and Karni's own commands: an app command of the same name is shadowed.
+BUILTIN = frozenset(
+    {
+        "changepassword",
+        "check",
+        "clearsessions",
+        "collectstatic",
+        "createsuperuser",
+        "dbshell",
+        "diffsettings",
+        "dumpdata",
+        "flush",
+        "inspectdb",
+        "karni_check",
+        "karni_context",
+        "karni_routes",
+        "karni_schedules",
+        "loaddata",
+        "makemigrations",
+        "migrate",
+        "runserver",
+        "sendtestemail",
+        "shell",
+        "showmigrations",
+        "spectacular",
+        "sqlflush",
+        "sqlmigrate",
+        "sqlsequencereset",
+        "squashmigrations",
+        "startapp",
+        "startproject",
+        "test",
+        "testserver",
+    }
+)
+
+
+def plan(ws: Workspace, app: App, name: str) -> None:
+    require_snake(name, "Command name")
+    if name in BUILTIN:
+        raise CliError(
+            f"`{name}` is a Django/Karni command — an app command of that name would be "
+            "shadowed. Choose another name.",
+            code="C103",
+        )
+    for package in ("management", "management/commands"):
+        init = app.file(*package.split("/"), "__init__.py")
+        if not ws.exists(init):
+            ws.create(init, "")
+    help_text = pystr(f"{humanize(name)}.")
+    done = pystr(f"{name}: done")
+    ws.create(
+        app.file("management", "commands", f"{name}.py"),
+        "from typing import Any\n\n"
+        "from django.core.management.base import BaseCommand\n\n\n"
+        "class Command(BaseCommand):\n"
+        f"    help = {help_text}\n\n"
+        "    def handle(self, *args: Any, **options: Any) -> None:\n"
+        f"        self.stdout.write(self.style.SUCCESS({done}))\n",
+    )
+    ws.note(f"run: karni manage {name}")
+
+
+def command(
+    name: str = typer.Argument(..., help="Command name, snake_case (e.g. send_reminders)."),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add a management command NAME to APP (run it with `karni manage NAME`)."""
+    ws = project_workspace(force)
+    plan(ws, resolve_app(ws, app), name)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/component.py

@@ -0,0 +1,115 @@
+"""``karni make component <Name>`` — a React component that claims a role.
+
+Every component registers its semantic role (``registerComponentRole`` from
+@karni/ui), so two components doing the same job fail loudly instead of
+drifting apart (K303: extend, never fork). A role @karni/ui or the project
+already claims is refused; replacing one on purpose takes ``--replace-reason``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+import typer
+
+from karni_cli.commands.context import find_manifest
+from karni_cli.generators.core import (
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    FRONTEND,
+    Workspace,
+    project_workspace,
+    require_frontend,
+)
+from karni_cli.generators.naming import kebab, require_kebab, require_pascal
+from karni_cli.project import CliError
+
+NAME = "component"
+SUMMARY = "Add a React component that claims a role (registerComponentRole)."
+
+COMPONENTS = FRONTEND / "src" / "components"
+_REGISTERED = re.compile(r"""registerComponentRole\(\s*["']([^"']+)["']\s*,\s*["']([^"']+)["']""")
+
+
+def _claimed(ws: Workspace, skip: str) -> dict[str, str]:
+    """``role -> owner`` from the @karni/ui manifest and the project's own sources."""
+    claimed: dict[str, str] = {}
+    manifest = find_manifest(ws.root, None)
+    if manifest is not None:
+        try:
+            roles = json.loads(manifest.read_text()).get("roles") or {}
+        except (OSError, json.JSONDecodeError):
+            roles = {}
+        claimed.update({role: f"@karni/ui's {owner}" for role, owner in roles.items()})
+    else:
+        ws.note("note: @karni/ui is not installed — its roles could not be checked.")
+    src = ws.path(FRONTEND / "src")
+    if src.is_dir():
+        for path in sorted(src.rglob("*.ts*")):
+            if "node_modules" in path.parts or ws.rel(path) == skip:
+                continue
+            text = ws.read(path) or ""
+            for role, owner in _REGISTERED.findall(text):
+                claimed[role] = f"{owner} ({ws.rel(path)})"
+    return claimed
+
+
+def plan(ws: Workspace, name: str, *, role: str | None, replace_reason: str | None) -> str:
+    require_frontend(ws)
+    component = require_pascal(name, "Component name")
+    role = require_kebab(role or kebab(component), "--role")
+    target = COMPONENTS / f"{component}.tsx"
+    owner = _claimed(ws, ws.rel(ws.path(target))).get(role)
+    options = ""
+    if owner is not None:
+        if not replace_reason:
+            raise CliError(
+                f"Role {role!r} is already claimed by {owner}. Compose or extend it instead "
+                "(K303), pick another --role, or replace it on purpose with "
+                '--replace-reason "<why>".',
+                code="C107",
+            )
+        reason = json.dumps(replace_reason)
+        options = f", {{ replace: true, reason: {reason} }}"
+    elif replace_reason:
+        raise CliError(f"--replace-reason: no component claims role {role!r} yet.", code="C106")
+    source = (
+        'import type { ReactNode } from "react";\n'
+        'import { registerComponentRole } from "@karni/ui";\n'
+        "\n"
+        f'registerComponentRole("{role}", "{component}"{options});\n'
+        "\n"
+        f"export interface {component}Props {{\n"
+        "    children?: ReactNode;\n"
+        "}\n"
+        "\n"
+        f"export function {component}({{ children }}: {component}Props) {{\n"
+        "    return <div>{children}</div>;\n"
+        "}\n"
+    )
+    ws.create(target, source)
+    ws.note(f"role: {role} -> {component}")
+    return role
+
+
+def command(
+    name: str = typer.Argument(..., help="Component name, PascalCase (e.g. StatusBadge)."),
+    role: str | None = typer.Option(
+        None, "--role", help="Semantic role it claims (default: kebab-case of NAME)."
+    ),
+    replace_reason: str | None = typer.Option(
+        None, "--replace-reason", help="Take over a role another component claims, saying why."
+    ),
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add frontend/src/components/NAME.tsx, registered with registerComponentRole.
+
+    A role already claimed by @karni/ui (its manifest) or by another project
+    component is refused — compose that component instead, or pass
+    --replace-reason to replace it on purpose.
+    """
+    ws = project_workspace(force)
+    plan(ws, name, role=role, replace_reason=replace_reason)
+    ws.commit(dry_run=dry_run)