karni-cli 0.3.1__py3-none-any.whl

karni_cli/generators/page.py

@@ -0,0 +1,373 @@
+"""``karni make page <name>`` — a ≤ 50-line page composing @karni/ui, routed.
+
+Kinds (``--resource R --kind ...``), with routes under a base path
+(``--path``, default ``/<resource>``):
+
+* ``list``   → ``<base>``: ``<Page><ResourceTable resource=R /></Page>``
+* ``detail`` → ``<base>/$id``: ``<ResourceDetail resource=R id={id} />``
+* ``form``   → ``<base>/new`` and ``<base>/$id/edit``: ``<ResourceForm />``
+
+Pages link to their siblings only when those routes exist (or are generated
+in the same run) — TanStack Router's typed ``navigate`` rejects unknown
+paths, so a link to a missing page would not compile. Without
+``--resource`` the page is a bare ``<Page title=... />`` at ``/<name>``.
+
+Routes are registered in ``frontend/src/routes.tsx`` between the
+``// karni:page-imports`` and ``// karni:routes`` markers.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+from karni_cli.generators.core import (
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    FRONTEND,
+    Workspace,
+    local_apps,
+    project_workspace,
+    require_frontend,
+)
+from karni_cli.generators.introspect import viewsets_file
+from karni_cli.generators.naming import default_route, humanize, pascal, require_kebab
+from karni_cli.generators.pysource import parse
+from karni_cli.project import CliError
+
+NAME = "page"
+SUMMARY = "Add a frontend page (<= 50 lines) composing @karni/ui, with its route."
+
+KINDS = ("list", "detail", "form", "login")
+MAX_LINES = 50
+PAGES = FRONTEND / "src" / "pages"
+ROUTES = FRONTEND / "src" / "routes.tsx"
+IMPORT_MARKER = "// karni:page-imports"
+ROUTE_MARKER = "// karni:routes"
+
+_PATH = re.compile(r"^/([A-Za-z0-9_.$-]+(/[A-Za-z0-9_.$-]+)*)?$")
+_ROUTE_PATH = re.compile(r"""path:\s*["']([^"']+)["']""")
+_SUFFIXES = ("-detail", "-form", "-list", "-page")
+
+
+@dataclass(frozen=True)
+class PageSpec:
+    name: str
+    kind: str | None
+    resource: str | None
+    base: str
+    title: str
+    #: Relation fields a detail page asks the API to expand (labels, not raw ids).
+    expand: tuple[str, ...] = ()
+
+    @property
+    def component(self) -> str:
+        stem = pascal(self.name)
+        return stem if stem.endswith("Page") else f"{stem}Page"
+
+    @property
+    def paths(self) -> list[str]:
+        if self.kind == "detail":
+            return [f"{self.base}/$id"]
+        if self.kind == "form":
+            return [f"{self.base}/new", f"{self.base}/$id/edit"]
+        return [self.base]
+
+    @property
+    def file(self) -> Path:
+        return PAGES / f"{self.name}.tsx"
+
+
+def spec_for(
+    name: str,
+    *,
+    resource: str | None,
+    kind: str | None,
+    path: str | None,
+    title: str | None = None,
+    expand: tuple[str, ...] | list[str] | None = None,
+) -> PageSpec:
+    require_kebab(name, "Page name")
+    if kind is not None and kind not in KINDS:
+        raise CliError(f"--kind {kind!r}: choose one of {', '.join(KINDS)}.", code="C106")
+    if kind is not None and kind != "login" and resource is None:
+        raise CliError(
+            f"--kind {kind} needs --resource <route>, e.g. --resource events.", code="C004"
+        )
+    if resource is not None:
+        require_kebab(resource, "--resource")
+        kind = kind or "list"
+    base = (path or f"/{resource or name}").rstrip("/") or "/"
+    if not _PATH.match(base):
+        raise CliError(f"--path {path!r} must look like /events or /admin/events.", code="C106")
+    if title is None:
+        stem = name
+        for suffix in _SUFFIXES:
+            stem = stem.removesuffix(suffix)
+        title = (
+            "Sign in"
+            if kind == "login"
+            else humanize(resource if kind == "list" and resource else stem)
+        )
+    if any(ch in title for ch in '"{}<>\\`'):
+        raise CliError(
+            f"--title {title!r}: plain text only (no quotes, braces or angle brackets).",
+            code="C106",
+        )
+    return PageSpec(name, kind, resource, base, title, tuple(expand or ()))
+
+
+def known_routes(ws: Workspace) -> set[str]:
+    text = ws.read(ROUTES) or ""
+    return set(_ROUTE_PATH.findall(text))
+
+
+def _routed_resources(ws: Workspace) -> set[str]:
+    """Routes of the project's viewsets (default kebab-plural, or an explicit ``route``)."""
+    found: set[str] = set()
+    for app in local_apps(ws):
+        path = viewsets_file(ws, app)
+        text = ws.read(path)
+        if not text:
+            continue
+        for node in parse(ws, ws.rel(path), text).body:
+            if not isinstance(node, ast.ClassDef):
+                continue
+            explicit = None
+            model = None
+            for stmt in node.body:
+                if not isinstance(stmt, ast.Assign) or len(stmt.targets) != 1:
+                    continue
+                target = stmt.targets[0]
+                if not isinstance(target, ast.Name):
+                    continue
+                if target.id == "route" and isinstance(stmt.value, ast.Constant):
+                    explicit = str(stmt.value.value)
+                elif target.id == "model" and isinstance(stmt.value, ast.Name):
+                    model = stmt.value.id
+            if explicit:
+                found.add(explicit)
+            elif model:
+                found.add(default_route(model))
+    return found
+
+
+# rendering
+
+
+def _ui_import(names: set[str]) -> str:
+    return "import { " + ", ".join(sorted(names)) + ' } from "@karni/ui";'
+
+
+def _router_import(names: set[str]) -> str:
+    return "import { " + ", ".join(sorted(names)) + ' } from "@tanstack/react-router";'
+
+
+def _go(to: str, params: str = "") -> str:
+    extra = f", params: {{ {params} }}" if params else ""
+    return f'void navigate({{ to: "{to}"{extra} }})'
+
+
+def render(spec: PageSpec, routes: set[str]) -> str:
+    """The page source; links only to routes in ``routes``."""
+    base = spec.base.rstrip("/")
+    if spec.kind is None:
+        return (
+            f"{_ui_import({'Page'})}\n\n"
+            f"export default function {spec.component}() {{\n"
+            f'    return <Page title="{spec.title}" />;\n'
+            "}\n"
+        )
+    if spec.kind == "login":
+        home = "/" if "/" in routes or not routes else min(routes)
+        props = [f"onSuccess={{() => {_go(home)}}}"]
+        return _shell(spec, "LoginForm", props, None, hooks=[], ui={"LoginForm"})
+    detail, new, edit = f"{base}/$id", f"{base}/new", f"{base}/$id/edit"
+    resource = spec.resource
+    if spec.kind == "list":
+        props = [f'resource="{resource}"']
+        if detail in routes:
+            props.append(f"onRowClick={{(row) =>\n    {_go(detail, 'id: String(row.id)')}\n}}")
+        if edit in routes:
+            props.append(f"onEdit={{(row) =>\n    {_go(edit, 'id: String(row.id)')}\n}}")
+        actions = f"<Button onClick={{() => {_go(new)}}}>New</Button>" if new in routes else None
+        return _shell(spec, "ResourceTable", props, actions, hooks=[], ui={"ResourceTable"})
+    if spec.kind == "detail":
+        hooks = [f'const {{ id }} = useParams({{ from: "{detail}" }});']
+        actions = None
+        if edit in routes:
+            actions = f"<Button onClick={{() => {_go(edit, 'id')}}}>\n    Edit\n</Button>"
+        props = [f'resource="{resource}"', "id={id}"]
+        if spec.expand:
+            names = ", ".join(f'"{name}"' for name in spec.expand)
+            props.append(f"expand={{[{names}]}}")
+        return _shell(spec, "ResourceDetail", props, actions, hooks=hooks, ui={"ResourceDetail"})
+    hooks = ["const { id } = useParams({ strict: false });"]
+    props = [f'resource="{resource}"', "id={id}"]
+    if detail in routes:
+        props.append(f"onSuccess={{(result) =>\n    {_go(detail, 'id: String(result.id)')}\n}}")
+    elif spec.base in routes:
+        props.append(f"onSuccess={{() => {_go(spec.base)}}}")
+    noun = spec.title.lower()
+    title = f'{{id === undefined ? "New {noun}" : "Edit {noun}"}}'
+    return _shell(spec, "ResourceForm", props, None, hooks=hooks, ui={"ResourceForm"}, title=title)
+
+
+def _indent(text: str, spaces: int) -> str:
+    pad = " " * spaces
+    return "\n".join(pad + line if line else line for line in text.split("\n"))
+
+
+def _shell(
+    spec: PageSpec,
+    element: str,
+    props: list[str],
+    actions: str | None,
+    *,
+    hooks: list[str],
+    ui: set[str],
+    title: str | None = None,
+) -> str:
+    body = "\n".join(props)
+    navigates = "navigate(" in body or (actions is not None and "navigate(" in actions)
+    if navigates:
+        hooks = [*hooks, "const navigate = useNavigate();"]
+    router: set[str] = set()
+    if any("useParams(" in hook for hook in hooks):
+        router.add("useParams")
+    if navigates:
+        router.add("useNavigate")
+    title_attr = f"title={title}" if title else f'title="{spec.title}"'
+    ui = {*ui, "Page", *({"Button"} if actions else set())}
+    lines = [_ui_import(ui)]
+    if router:
+        lines.append(_router_import(router))
+    lines += ["", f"export default function {spec.component}() {{"]
+    lines += [f"    {hook}" for hook in hooks]
+    lines.append("    return (")
+    if actions:
+        lines += ["        <Page", f"            {title_attr}", "            actions={"]
+        lines.append(_indent(actions, 16))
+        lines += ["            }", "        >"]
+    else:
+        lines.append(f"        <Page {title_attr}>")
+    if len(props) == 1:
+        lines.append(f"            <{element} {props[0]} />")
+    elif all("\n" not in p for p in props) and len(" ".join(props)) <= 50:
+        lines.append(f"            <{element} {' '.join(props)} />")
+    else:
+        lines.append(f"            <{element}")
+        lines += [_indent(prop, 16) for prop in props]
+        lines.append("            />")
+    lines += ["        </Page>", "    );", "}", ""]
+    return "\n".join(lines)
+
+
+# planning
+
+
+def plan(
+    ws: Workspace,
+    spec: PageSpec,
+    *,
+    register: bool = True,
+    planned_routes: set[str] | None = None,
+) -> None:
+    """Plan the page file and its route entries."""
+    require_frontend(ws)
+    existing = known_routes(ws)
+    routes = existing | set(planned_routes or ()) | set(spec.paths)
+    source = render(spec, routes)
+    count = source.count("\n")
+    if count > MAX_LINES:  # pragma: no cover - the templates stay far below the cap
+        raise CliError(f"internal: generated page is {count} lines (cap {MAX_LINES}).", code="C199")
+    ws.create(spec.file, source)
+    if spec.resource and spec.resource not in _routed_resources(ws):
+        ws.note(
+            f"note: no viewset in this project routes /api/{spec.resource}/ yet — "
+            "karni make viewset <Model> (or point --resource at a module's resource)."
+        )
+    if register:
+        _register(ws, spec, existing)
+    else:
+        ws.note(f"route not registered (--no-route): add {', '.join(spec.paths)} yourself.")
+    ws.note(f"page: {', '.join(spec.paths)} -> {spec.component}")
+
+
+def _register(ws: Workspace, spec: PageSpec, existing: set[str]) -> None:
+    text = ws.read(ROUTES)
+    manual = f'import {spec.component} from "./pages/{spec.name}";\n' + "\n".join(
+        _route_line(spec, p) for p in spec.paths
+    )
+    if text is None or IMPORT_MARKER not in text or ROUTE_MARKER not in text:
+        raise CliError(
+            f"{ROUTES.as_posix()} with the `{IMPORT_MARKER}` and `{ROUTE_MARKER}` markers "
+            "was not found (projects scaffolded before `karni make`). Register the route "
+            f"yourself and re-run with --no-route:\n{manual}",
+            code="C108",
+        )
+    lines = text.splitlines()
+    import_line = f'import {spec.component} from "./pages/{spec.name}";'
+    for path in spec.paths:
+        if path in existing:
+            owner = next((ln for ln in lines if f'"{path}"' in ln), "")
+            if f"component: {spec.component}" not in owner:
+                raise CliError(
+                    f"Route {path} is already registered in {ROUTES.as_posix()} — choose "
+                    "another --path (or remove the existing route).",
+                    code="C107",
+                )
+    if import_line not in lines:
+        index = next(i for i, ln in enumerate(lines) if IMPORT_MARKER in ln)
+        lines.insert(index, import_line)
+    for path in spec.paths:
+        if path in existing:
+            continue
+        index = next(i for i, ln in enumerate(lines) if ROUTE_MARKER in ln)
+        indent = lines[index][: len(lines[index]) - len(lines[index].lstrip())]
+        lines.insert(index, indent + _route_line(spec, path).strip())
+    ws.write(ROUTES, "\n".join(lines) + "\n")
+
+
+def _route_line(spec: PageSpec, path: str) -> str:
+    return (
+        f'    createRoute({{ getParentRoute: () => root, path: "{path}", '
+        f"component: {spec.component} }}),"
+    )
+
+
+def command(
+    name: str = typer.Argument(..., help="Page file name, kebab-case (e.g. events)."),
+    resource: str | None = typer.Option(
+        None, "--resource", help="API resource (router prefix, e.g. events)."
+    ),
+    kind: str | None = typer.Option(
+        None,
+        "--kind",
+        help="With --resource: list (default), detail or form; login needs no resource.",
+    ),
+    path: str | None = typer.Option(
+        None, "--path", help="Route path (resource pages: the base, default /<resource>)."
+    ),
+    title: str | None = typer.Option(None, "--title", help="Page title (default: from the name)."),
+    no_route: bool = typer.Option(
+        False, "--no-route", help="Do not register the route in frontend/src/routes.tsx."
+    ),
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add frontend/src/pages/NAME.tsx (<= 50 lines) and register its route.
+
+    --resource R --kind list|detail|form composes ResourceTable /
+    ResourceDetail / ResourceForm for the API resource R; without --resource
+    the page is a bare <Page>. Routes: list <base>, detail <base>/$id, form
+    <base>/new and <base>/$id/edit, base = --path or /<resource>.
+    """
+    ws = project_workspace(force)
+    spec = spec_for(name, resource=resource, kind=kind, path=path, title=title)
+    plan(ws, spec, register=not no_route)
+    ws.commit(dry_run=dry_run)

karni_cli/generators/pysource.py

@@ -0,0 +1,304 @@
+"""AST-located edits and ruff-clean rendering of generated Python.
+
+Generators never regex-rewrite Python. They parse the file, locate top-level
+statements by AST position, and either append a block or replace one
+statement's lines. Imports are merged into the leading import block and
+re-rendered the way ruff's isort and formatter lay them out (sections,
+straight-before-from, order-by-type, wrapping at the project's line length);
+a block that carries comments is never re-rendered — missing imports are
+appended after it instead.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import textwrap
+from dataclasses import dataclass
+
+from karni_cli.generators.core import Workspace
+from karni_cli.project import CliError
+
+_DEF_LIKE = re.compile(r"^(class |def |async def |@)")
+
+
+@dataclass(frozen=True, order=True)
+class Import:
+    """``from module import name [as alias]``; ``name=None`` is ``import module [as alias]``."""
+
+    module: str
+    name: str | None = None
+    alias: str | None = None
+    level: int = 0
+
+
+def parse(ws: Workspace, rel: object, text: str) -> ast.Module:
+    try:
+        return ast.parse(text)
+    except SyntaxError as exc:
+        raise CliError(
+            f"{rel}:{exc.lineno}: cannot parse ({exc.msg}) — fix the file, then re-run.",
+            code="C110",
+        ) from None
+
+
+# locating statements
+
+
+def top_level(tree: ast.Module, name: str) -> ast.stmt | None:
+    """The top-level class, function or simple assignment binding ``name``."""
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef):
+            if node.name == name:
+                return node
+        elif isinstance(node, ast.Assign):
+            if any(isinstance(t, ast.Name) and t.id == name for t in node.targets):
+                return node
+        elif (
+            isinstance(node, ast.AnnAssign)
+            and isinstance(node.target, ast.Name)
+            and node.target.id == name
+        ):
+            return node
+    return None
+
+
+def span(lines: list[str], node: ast.stmt) -> tuple[int, int]:
+    """1-based ``(first, last)`` lines of ``node``: decorators and the comments right above."""
+    decorators = getattr(node, "decorator_list", [])
+    first = min([node.lineno, *(d.lineno for d in decorators)])
+    while first > 1 and lines[first - 2].lstrip().startswith("#"):
+        first -= 1
+    last = node.end_lineno or node.lineno
+    # Trailing comments indented into the body belong to it (the AST ends at code).
+    while last < len(lines):
+        following = lines[last]
+        indent = len(following) - len(following.lstrip())
+        if not following.lstrip().startswith("#") or indent <= node.col_offset:
+            break
+        last += 1
+    return first, last
+
+
+def replace_span(text: str, first: int, last: int, block: str) -> str:
+    lines = text.splitlines()
+    lines[first - 1 : last] = block.rstrip("\n").splitlines()
+    return "\n".join(lines) + "\n"
+
+
+def _def_like(block: str) -> bool:
+    for line in block.splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            return bool(_DEF_LIKE.match(stripped))
+    return False
+
+
+def append(text: str, block: str) -> str:
+    """``block`` appended as new top-level code, separated the way ruff formats it."""
+    body = text.rstrip()
+    block = block.strip("\n")
+    if not body:
+        return block + "\n"
+    tree = ast.parse(text)
+    last = tree.body[-1] if tree.body else None
+    previous_def = isinstance(last, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef)
+    gap = "\n\n\n" if _def_like(block) or previous_def else "\n\n"
+    return f"{body}{gap}{block}\n"
+
+
+def replace_or_append(ws: Workspace, rel: object, text: str, name: str, block: str) -> str:
+    """Append ``block``; when ``name`` is already bound at top level, replace it (``--force``)."""
+    tree = parse(ws, rel, text)
+    existing = top_level(tree, name)
+    if existing is None:
+        return append(text, block)
+    ws.refuse_existing(f"{name} in {rel}")
+    first, last = span(text.splitlines(), existing)
+    return replace_span(text, first, last, block)
+
+
+# imports
+
+
+def _bound(tree: ast.Module) -> set[Import]:
+    found: set[Import] = set()
+    for node in tree.body:
+        if isinstance(node, ast.Import):
+            found |= {Import(a.name, None, a.asname) for a in node.names}
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module or ""
+            found |= {Import(module, a.name, a.asname, node.level) for a in node.names}
+    return found
+
+
+def _leading_run(tree: ast.Module) -> tuple[list[ast.stmt], bool]:
+    """The contiguous top-level import statements at the top, and whether a docstring precedes."""
+    body = list(tree.body)
+    has_doc = bool(
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    )
+    run: list[ast.stmt] = []
+    for node in body[1:] if has_doc else body:
+        if not isinstance(node, ast.Import | ast.ImportFrom):
+            break
+        run.append(node)
+    return run, has_doc
+
+
+def _member_key(name: str) -> tuple[int, str, str]:
+    """ruff's ``order-by-type``: CONSTANTS, then Classes, then functions/variables."""
+    if name.isupper() and len(name) > 1:
+        kind = 0
+    elif name[:1].isupper():
+        kind = 1
+    else:
+        kind = 2
+    return kind, name.lower(), name
+
+
+def _module_key(module: str) -> tuple[str, str]:
+    return module.lower(), module
+
+
+def render_imports(ws: Workspace, imports: set[Import]) -> str:
+    """The import block for ``imports`` laid out as ruff's isort does."""
+    sections: dict[int, list[Import]] = {}
+    for item in imports:
+        sections.setdefault(ws.import_section(item.module, item.level), []).append(item)
+    blocks: list[str] = []
+    for section in sorted(sections):
+        items = sections[section]
+        lines: list[str] = []
+        straight = sorted((i for i in items if i.name is None), key=lambda i: _module_key(i.module))
+        for item in straight:
+            alias = f" as {item.alias}" if item.alias else ""
+            lines.append(f"import {item.module}{alias}")
+        grouped: dict[tuple[int, str], list[Import]] = {}
+        for item in items:
+            if item.name is not None:
+                grouped.setdefault((item.level, item.module), []).append(item)
+        for level, module in sorted(grouped, key=lambda k: (_module_key(k[1]), k[0])):
+            members = grouped[(level, module)]
+            source = "." * level + module
+            plain = sorted({m.name for m in members if not m.alias and m.name}, key=_member_key)
+            if plain:
+                lines.append(_from_line(source, plain, ws.line_length))
+            aliased = sorted(
+                (m for m in members if m.alias), key=lambda m: _member_key(m.name or "")
+            )
+            for member in aliased:
+                lines.append(f"from {source} import {member.name} as {member.alias}")
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def _from_line(source: str, names: list[str], line_length: int) -> str:
+    single = f"from {source} import {', '.join(names)}"
+    if len(single) <= line_length:
+        return single
+    body = "".join(f"    {name},\n" for name in names)
+    return f"from {source} import (\n{body})"
+
+
+def ensure_imports(ws: Workspace, rel: object, text: str, wanted: list[Import]) -> str:
+    """``text`` with every import in ``wanted`` present (merged into the leading block)."""
+    tree = parse(ws, rel, text)
+    present = _bound(tree)
+    missing = {item for item in wanted if item not in present}
+    if not missing:
+        return text
+    lines = text.splitlines()
+    run, has_doc = _leading_run(tree)
+    if run:
+        first = run[0].lineno
+        last = run[-1].end_lineno or run[-1].lineno
+        region = lines[first - 1 : last]
+        if any("#" in line for line in region):
+            # A commented block is never re-rendered: append after it instead.
+            addition = render_imports(ws, missing).replace("\n\n", "\n")
+            lines[last:last] = addition.splitlines()
+            return "\n".join(lines) + "\n"
+        merged = _bound(_module_of(run)) | missing
+        lines[first - 1 : last] = render_imports(ws, merged).splitlines()
+        return "\n".join(lines) + "\n"
+    block = render_imports(ws, missing)
+    if has_doc:
+        doc_end = tree.body[0].end_lineno or tree.body[0].lineno
+        head, rest = lines[:doc_end], lines[doc_end:]
+    else:
+        head, rest = [], lines
+    while rest and not rest[0].strip():
+        rest.pop(0)
+    parts = [*head, *([""] if head else []), *block.splitlines()]
+    if rest:
+        gap = ["", ""] if _def_like("\n".join(rest)) else [""]
+        parts += [*gap, *rest]
+    return "\n".join(parts) + "\n"
+
+
+def _module_of(nodes: list[ast.stmt]) -> ast.Module:
+    return ast.Module(body=nodes, type_ignores=[])
+
+
+# rendering
+
+
+def pystr(value: str) -> str:
+    """A string literal in ruff format's preferred quotes."""
+    if '"' in value and "'" not in value:
+        return "'" + value.replace("\\", "\\\\") + "'"
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def call(
+    head: str,
+    args: list[str],
+    indent: str,
+    line_length: int,
+    tail: str = "",
+    *,
+    collection: bool = False,
+) -> str:
+    """``{indent}{head}(args){tail}`` split the way ruff format splits it.
+
+    ruff format hugs call arguments on one indented line when they fit; a
+    collection literal (``collection=True``) that does not fit is always
+    split one element per line, with a trailing comma.
+    """
+    flat = f"{indent}{head}({', '.join(args)}){tail}"
+    if len(flat) <= line_length or not args:
+        return flat
+    inner = f"{indent}    {', '.join(args)}"
+    if len(inner) <= line_length and not collection:
+        return f"{indent}{head}(\n{inner}\n{indent}){tail}"
+    body = "".join(f"{indent}    {arg},\n" for arg in args)
+    return f"{indent}{head}(\n{body}{indent}){tail}"
+
+
+def tuple_literal(head: str, items: list[str], indent: str, line_length: int) -> str:
+    """``{indent}{head}(a, b)``: ``(a,)`` for one item, one item per line when too long."""
+    if len(items) == 1:
+        flat = f"{indent}{head}({items[0]},)"
+        if len(flat) <= line_length:
+            return flat
+    return call(head, items, indent, line_length, collection=True)
+
+
+def docstring(text: str, indent: str, line_length: int) -> str:
+    """A docstring statement wrapped to the line length."""
+    flat = f'{indent}"""{text}"""'
+    if len(flat) <= line_length:
+        return flat
+    wrapped = textwrap.wrap(text, width=max(line_length - len(indent) - 3, 20))
+    lines = [f'{indent}"""{wrapped[0]}', *(f"{indent}{line}" for line in wrapped[1:])]
+    return "\n".join([*lines, f'{indent}"""'])
+
+
+def comment(text: str, indent: str, line_length: int, prefix: str = "# ") -> str:
+    """A comment wrapped to the line length."""
+    width = max(line_length - len(indent) - len(prefix), 20)
+    return "\n".join(f"{indent}{prefix}{line}" for line in textwrap.wrap(text, width=width))