deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/doc.py

@@ -0,0 +1,529 @@
+"""``deepcell doc`` — read and edit a `<Document>` prose section.
+
+Mirrors ``backend/jingwei_api/routers/document.py`` 1:1. Every subcommand
+answers from the server-built RenderPlan, so what the CLI prints is exactly
+what the viewer renders — a reference is resolved once, server-side, and never
+re-resolved per surface.
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.commands.defs import _apply
+from deepcell_cli.commands._write_opts import WriteCommand
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_info, echo_success, output, print_plain
+
+
+@click.group()
+def doc() -> None:
+    """Read and edit the prose documents in a .deepcell file."""
+
+
+def _body(ctx: Ctx, filename: str, **extra) -> dict:
+    body: dict = {
+        "workspace_slug": ctx.require_workspace(),
+        "source_filename": filename,
+    }
+    body.update({key: value for key, value in extra.items() if value is not None})
+    return body
+
+
+@doc.command("list")
+@click.argument("filename")
+@pass_ctx
+def list_docs(ctx: Ctx, filename: str) -> None:
+    """List every <Document> in the file."""
+    data = ctx.client.post("/document/list", json=_body(ctx, filename))
+    documents = data.get("documents", [])
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+        return
+    if not documents:
+        echo_info("This file has no <Document> section.")
+        return
+    for document in documents:
+        print_plain(
+            f"{document['doc_id']}  {document.get('name') or ''}"
+            f"  ({document.get('block_count', 0)} blocks,"
+            f" {document.get('link_count', 0)} links,"
+            f" {document.get('warning_count', 0)} warnings)"
+        )
+
+
+@doc.command("show")
+@click.argument("filename")
+@click.option("--doc", "doc_id", default=None, help="Document ID (default: the first).")
+@click.option("--scenario", "scenario_id", default=None, help="Scenario to resolve values under.")
+@click.option(
+    # NOT `--format`: that is a ROOT option (`-f json|table|plain`), parsed
+    # before the subcommand by `FlexibleGroup._GLOBAL_VALUE_OPTS`. A per-command
+    # `--format` with a different vocabulary both shadows it and can be taken
+    # for the global while the subcommand is still being located.
+    # `test_surface_walker.py::test_globals_are_the_root_group_s_options` pins
+    # this for every command.
+    "--as", "rendering", type=click.Choice(["text", "markdown"]),
+    default="text",
+    help="markdown keeps the [[deepcell:...]] source; text shows resolved values.",
+)
+@click.option(
+    "--with-ids", is_flag=True, default=False,
+    help="Prefix each block with the id it can be edited by.",
+)
+@pass_ctx
+def show_doc(ctx: Ctx, filename: str, doc_id: str | None, scenario_id: str | None,
+             rendering: str, with_ids: bool) -> None:
+    """Print one document. `text` shows what a reader sees; `markdown` the source.
+
+    JSON comes from the root flag, `deepcell -f json doc show …`, like every
+    other command — this option chooses which *prose* to print, not which
+    envelope to print it in.
+    """
+    data = ctx.client.post(
+        "/document/show",
+        json=_body(ctx, filename, doc_id=doc_id, scenario_id=scenario_id),
+    )
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+        return
+    key = "markdown" if rendering == "markdown" else "text"
+    for block in data.get("blocks", []):
+        if with_ids:
+            # `(unstamped)` rather than a blank: a block with no id is exactly
+            # the one no per-block command can address, and saying so beats
+            # printing a gap the reader has to interpret.
+            print_plain(f"[{block.get('block_id') or '(unstamped)'}]")
+        print_plain(block.get(key, ""))
+        print_plain("")
+    for warning in data.get("warnings", []):
+        echo_info(f"{warning['code']}: {warning['message']}")
+
+
+@doc.command("blocks")
+@click.argument("filename")
+@click.option("--doc", "doc_id", default=None, help="Document ID (default: the first).")
+@pass_ctx
+def doc_blocks(ctx: Ctx, filename: str, doc_id: str | None) -> None:
+    """List every block and the id it can be edited by.
+
+    `outline` shows headings and `show` shows prose; this is the one that
+    answers "what can I edit, and what do I call it?". Every per-block command
+    below takes an id from here.
+
+    A block printed as `(unstamped)` has no id yet and cannot be addressed —
+    run `deepcell doc stamp-ids` to mint one for every such block.
+    """
+    data = ctx.client.post("/document/blocks", json=_body(ctx, filename, doc_id=doc_id))
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+        return
+    blocks = data.get("blocks", [])
+    if not blocks:
+        echo_info("This document has no blocks.")
+        return
+    for block in blocks:
+        block_id = block.get("block_id") or "(unstamped)"
+        print_plain(f"{block_id:14} {block.get('kind', ''):8} {block.get('preview', '')}")
+    unstamped = data.get("unstamped") or 0
+    if unstamped:
+        echo_info(
+            f"{unstamped} block(s) have no id and cannot be edited individually. "
+            f"Run: deepcell doc stamp-ids {filename}"
+        )
+
+
+@doc.command("outline")
+@click.argument("filename")
+@click.option("--doc", "doc_id", default=None, help="Document ID (default: the first).")
+@pass_ctx
+def outline_doc(ctx: Ctx, filename: str, doc_id: str | None) -> None:
+    """Print the headings and the anchor each one is addressable by."""
+    data = ctx.client.post(
+        "/document/outline", json=_body(ctx, filename, doc_id=doc_id)
+    )
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+        return
+    for heading in data.get("headings", []):
+        indent = "  " * max(0, int(heading.get("level", 1)) - 1)
+        print_plain(f"{indent}{heading.get('text', '')}  #{heading.get('anchor')}")
+
+
+@doc.command("links")
+@click.argument("filename")
+@click.option("--doc", "doc_id", default=None, help="Restrict to one document.")
+@click.option("--unresolved", "unresolved_only", is_flag=True, default=False, help="Only references that did not resolve.")
+@pass_ctx
+def doc_links(ctx: Ctx, filename: str, doc_id: str | None, unresolved_only: bool) -> None:
+    """List every deepcell: reference, and whether it resolved."""
+    data = ctx.client.post(
+        "/document/links",
+        json=_body(ctx, filename, doc_id=doc_id, unresolved_only=unresolved_only or None),
+    )
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+        return
+    links = data.get("links", [])
+    if not links:
+        echo_info("No unresolved references." if unresolved_only else "No references.")
+        return
+    for link in links:
+        mark = "ok " if link.get("resolved") else "MISS"
+        anchor = f"#{link['anchor']}" if link.get("anchor") else ""
+        print_plain(f"{mark} {link['doc_id']}{anchor}  {link['ref']}  -> {link.get('text','')}")
+        if link.get("hint"):
+            print_plain(f"      hint: {link['hint']}")
+
+
+@doc.command("lint")
+@click.argument("filename")
+@click.option("--doc", "doc_id", default=None, help="Restrict to one document.")
+@click.option(
+    "--strict", is_flag=True, default=False,
+    help="Also flag numerals that match a modelled value but are typed, not linked.",
+)
+@pass_ctx
+def doc_lint(ctx: Ctx, filename: str, doc_id: str | None, strict: bool) -> None:
+    """Check a document's references. Exits non-zero on any error finding.
+
+    `--strict` adds `unlinked_numeral`, which is opt-in because the general
+    form is not specifiable — the same number matches base, bull and bear, and
+    nothing separates a modelled value from a year or a headcount. The narrow
+    form it does check: a numeral matching the resolved default-scenario value
+    of a cell whose item label appears within ten words.
+    """
+    data = ctx.client.post(
+        "/document/lint",
+        json=_body(ctx, filename, doc_id=doc_id, strict=strict or None),
+    )
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+    else:
+        findings = data.get("findings", [])
+        if not findings:
+            echo_info("No findings.")
+        for finding in findings:
+            anchor = f"#{finding['anchor']}" if finding.get("anchor") else ""
+            print_plain(
+                f"[{finding.get('severity', 'warn')}] {finding.get('code')} "
+                f"{finding.get('doc_id')}{anchor}: {finding.get('message')}"
+            )
+    if data.get("error_count"):
+        raise SystemExit(1)
+
+
+@doc.command("backlinks")
+@click.argument("filename")
+@click.option("--target", required=True, help="Reference to invert, e.g. 'claim/t_hold'.")
+@pass_ctx
+def doc_backlinks(ctx: Ctx, filename: str, target: str) -> None:
+    """Show what cites a reference: prose, slides and reasoning, this file only.
+
+    --target is matched exactly, on the canonical form of the reference. The
+    kind is part of that form: `item/Revenue` finds citations of the row and
+    never a `cell/Revenue[FY2025]#projected` citation of one of its cells, so
+    ask once per address a reader may have written. A cell reference is
+    canonically status-qualified, so a bare one finds nothing — on zero
+    matches the suffixed variants in the index are printed as suggestions.
+
+    Use this in the cross-surface reassessment described by
+    `deepcell guide revise/premise-change`; `deepcell impact show` inverts
+    every changed address at once.
+    """
+    data = ctx.client.post(
+        "/document/backlinks", json=_body(ctx, filename, target=target)
+    )
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+        return
+    resolved = data.get("target", target)
+    coverage = ", ".join(data.get("coverage") or ()) or "doc"
+    backlinks = data.get("backlinks", [])
+    if not backlinks:
+        # A zero is stated, never hidden — and it is stated together with what
+        # was searched. "Nothing cites this" and "nothing I looked at cites
+        # this" are different answers, and only one of them is honest here.
+        echo_info(f"Nothing in this file cites {resolved} (searched: {coverage}).")
+        # A third answer the zero used to swallow: the index holds the same
+        # reference with a status suffix. Matching is exact, and a cell
+        # reference is canonically status-qualified, so a reader inverting
+        # "what cites Revenue in FY2025" gets zero while the suffixed variant
+        # sits there. Suggested, never substituted — a status-qualified
+        # reference is a different address, and only the caller can say the
+        # two mean the same cell.
+        for near in data.get("near_targets") or ():
+            echo_info(f"  Indexed with a status: {near}")
+        return
+    print_plain(f"{resolved} — cited in this file by ({coverage}):")
+    for link in backlinks:
+        kind = link.get("source_kind") or "doc"
+        where = link.get("source_id") or link.get("source_doc_id") or "?"
+        anchor = f"#{link['source_anchor']}" if link.get("source_anchor") else ""
+        mode = f"  ({link['mode']})" if link.get("mode") else ""
+        print_plain(f"  {kind}: {where}{anchor}{mode}")
+
+
+@doc.command("set-body", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("--body-file", type=click.Path(exists=True, dir_okay=False), required=True,
+              help="File holding the new body.")
+@click.option("--notation", type=click.Choice(["markdown", "text"]), default=None,
+              help="What the body IS. Omitted keeps whatever the document "
+                   "already declared, so editing text never retypes it.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None,
+              help="Compare-and-swap token from `cat` (refuses if the file moved).")
+@pass_ctx
+def set_body(ctx: Ctx, filename: str, doc_id: str, body_file: str,
+             notation: str | None, rationale: str | None,
+             revision: str | None) -> None:
+    """Replace a document's whole body.
+
+    A body is ONE string, so two agents editing one document is a lost update
+    rather than a merge — pass `--revision` (from `deepcell cat`) and a
+    concurrent write is refused with the current revision instead of silently
+    winning.
+
+    `--notation` says what the bytes are: `markdown` or `text`. Omit it and the
+    document keeps whatever it already declared, so replacing the text of a
+    markdown memo cannot silently demote it to plain text. To change only the
+    notation, use `doc set-notation`, which leaves the bytes alone.
+    """
+    with open(body_file, "r", encoding="utf-8") as handle:
+        body = handle.read()
+    op = {"kind": "set_document_body", "docId": doc_id, "body": body}
+    if notation:
+        op["notation"] = notation
+    _apply_doc_op(ctx, filename, op, rationale, revision)
+    echo_success(f"Replaced the body of '{doc_id}'.")
+
+
+@doc.command("patch-body", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("--anchor", required=True,
+              help="Explicit {#id} anchor of the section to replace.")
+@click.option("--markdown", required=True, help="Replacement markdown for that section.")
+@click.option("--notation", type=click.Choice(["markdown", "text"]), default=None,
+              help="What the body IS. Omitted keeps whatever the document "
+                   "already declared, so editing text never retypes it.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None, help="Compare-and-swap token from `cat`.")
+@pass_ctx
+def patch_body(ctx: Ctx, filename: str, doc_id: str, anchor: str, markdown: str,
+               notation: str | None, rationale: str | None,
+               revision: str | None) -> None:
+    """Replace one anchored section of a document.
+
+    The anchor must be an explicit `{#id}`, not a heading slug: a slug is
+    derived from the heading text, so a retitle between read and write would
+    relocate the patch. Run `deepcell doc outline` to see which anchors are
+    explicit.
+    """
+    op = {
+        "kind": "patch_document_body",
+        "docId": doc_id,
+        "anchor": anchor,
+        "markdown": markdown,
+    }
+    if notation:
+        op["notation"] = notation
+    _apply_doc_op(ctx, filename, op, rationale, revision)
+    echo_success(f"Patched '{doc_id}' at #{anchor}.")
+
+
+@doc.command("set-notation", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("--notation", type=click.Choice(["markdown", "text"]), required=True,
+              help="What the body IS.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None, help="Compare-and-swap token from `cat`.")
+@pass_ctx
+def set_notation(ctx: Ctx, filename: str, doc_id: str, notation: str,
+                 rationale: str | None, revision: str | None) -> None:
+    """Say what a document's body IS, without touching a byte of it.
+
+    Use this to declare an existing plain-text body as markdown, or to demote
+    one back. Because it never re-sends the text, the change review headlines
+    the notation rather than showing the whole body as rewritten.
+
+    Notation is never sniffed: a body full of `**bold**` stays plain text until
+    something says otherwise. A body that looks like markdown and a body that
+    merely contains an asterisk are indistinguishable, and guessing is how a
+    reader ends up disagreeing with the file.
+    """
+    _apply_doc_op(
+        ctx, filename,
+        {"kind": "set_body_notation", "docId": doc_id, "notation": notation},
+        rationale, revision,
+    )
+    echo_success(f"'{doc_id}' now declares its body as {notation}.")
+
+
+@doc.command("stamp-ids", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None, help="Compare-and-swap token from `cat`.")
+@pass_ctx
+def stamp_ids(ctx: Ctx, filename: str, doc_id: str, rationale: str | None,
+              revision: str | None) -> None:
+    """Give every block without an id a stable `{#id}`, so it can be edited.
+
+    Idempotent, and it never touches an anchor an author wrote — `{#valuation}`
+    keeps meaning what they meant. Only blocks with no anchor at all get one.
+
+    This rewrites the whole body once, which is a large diff on a document that
+    has never been stamped and no diff at all on one that has. Every later edit
+    touches only the block it names.
+    """
+    _apply_doc_op(
+        ctx, filename,
+        {"kind": "stamp_document_ids", "docId": doc_id},
+        rationale or "Stamp block ids", revision,
+    )
+    echo_success(f"Stamped block ids in '{doc_id}'.")
+
+
+@doc.command("replace-block", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("--block", "block_id", required=True,
+              help="Block id from `deepcell doc blocks`.")
+@click.option("--markdown-file", type=click.Path(exists=True, dir_okay=False),
+              required=True, help="File holding the replacement markdown.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None, help="Compare-and-swap token from `cat`.")
+@pass_ctx
+def replace_block(ctx: Ctx, filename: str, doc_id: str, block_id: str,
+                  markdown_file: str, rationale: str | None,
+                  revision: str | None) -> None:
+    """Replace one block, addressed by its id.
+
+    The id is kept for you: a replacement that does not repeat `{#id}` has it
+    re-stamped, because the id is how the block is linked and bookmarked. A
+    replacement carrying a *different* id is refused rather than performed —
+    renaming strands every reference to the old one.
+    """
+    with open(markdown_file, "r", encoding="utf-8") as handle:
+        markdown = handle.read()
+    _apply_doc_op(
+        ctx, filename,
+        {"kind": "replace_document_block", "docId": doc_id, "blockId": block_id,
+         "markdown": markdown},
+        rationale, revision,
+    )
+    echo_success(f"Replaced block '{block_id}' in '{doc_id}'.")
+
+
+@doc.command("insert-block", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("--after", "after_block_id", default=None,
+              help="Insert after this block id. Omit to insert at the top.")
+@click.option("--markdown-file", type=click.Path(exists=True, dir_okay=False),
+              required=True, help="File holding the new block's markdown.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None, help="Compare-and-swap token from `cat`.")
+@pass_ctx
+def insert_block(ctx: Ctx, filename: str, doc_id: str, after_block_id: str | None,
+                 markdown_file: str, rationale: str | None,
+                 revision: str | None) -> None:
+    """Insert a new block after another one, or at the top of the document.
+
+    Position is named, never numbered: there is no `--at N`, because an index
+    is stale the moment anything above it moves. The new block is stamped with
+    an id, which is printed so you can address it next.
+    """
+    with open(markdown_file, "r", encoding="utf-8") as handle:
+        markdown = handle.read()
+    op: dict = {"kind": "insert_document_block", "docId": doc_id, "markdown": markdown}
+    if after_block_id:
+        op["afterBlockId"] = after_block_id
+    _apply_doc_op(ctx, filename, op, rationale, revision)
+    where = f"after '{after_block_id}'" if after_block_id else "at the top"
+    echo_success(f"Inserted a block {where} of '{doc_id}'.")
+
+
+@doc.command("delete-block", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("--block", "block_id", required=True, help="Block id to delete.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None, help="Compare-and-swap token from `cat`.")
+@pass_ctx
+def delete_block(ctx: Ctx, filename: str, doc_id: str, block_id: str,
+                 rationale: str | None, revision: str | None) -> None:
+    """Delete one block.
+
+    Refused when something still cites the block's id — a dangling
+    `[[deepcell:doc/…#id]]` is the defect the rename cascade exists to prevent,
+    so the citers are named instead and you decide what happens to them.
+    """
+    _apply_doc_op(
+        ctx, filename,
+        {"kind": "delete_document_block", "docId": doc_id, "blockId": block_id},
+        rationale, revision,
+    )
+    echo_success(f"Deleted block '{block_id}' from '{doc_id}'.")
+
+
+@doc.command("move-block", cls=WriteCommand)
+@click.argument("filename")
+@click.option("--doc", "doc_id", required=True, help="Document ID.")
+@click.option("--block", "block_id", required=True, help="Block id to move.")
+@click.option("--after", "after_block_id", default=None,
+              help="Move after this block id. Omit to move to the top.")
+@click.option("-m", "--message", "--rationale", "rationale", default=None,
+              help="Commit message recording why.")
+@click.option("--revision", default=None, help="Compare-and-swap token from `cat`.")
+@pass_ctx
+def move_block(ctx: Ctx, filename: str, doc_id: str, block_id: str,
+               after_block_id: str | None, rationale: str | None,
+               revision: str | None) -> None:
+    """Move a block after another one, or to the top.
+
+    Both ends are named rather than numbered, which is the only reason a
+    reorder is expressible at all: with indices it would be a delete plus an
+    insert against numbers the delete had just invalidated.
+    """
+    op: dict = {"kind": "move_document_block", "docId": doc_id, "blockId": block_id}
+    if after_block_id:
+        op["afterBlockId"] = after_block_id
+    _apply_doc_op(ctx, filename, op, rationale, revision)
+    where = f"after '{after_block_id}'" if after_block_id else "to the top"
+    echo_success(f"Moved block '{block_id}' {where}.")
+
+
+def _apply_doc_op(ctx: Ctx, filename: str, op: dict, rationale: str | None,
+                  revision: str | None) -> None:
+    """Send one op through the shared defs-ops envelope.
+
+    Delegates rather than building the body here. Spelling it a second time is
+    what broke both write commands: `filename` was sent as `source_filename`
+    (a 422 on every call) and `expected_revision` as `revision`, which pydantic
+    ignored — so the compare-and-swap these commands document never armed and a
+    concurrent write silently won the lost update they promise to refuse.
+    """
+    _apply(
+        ctx,
+        ctx.require_workspace(),
+        filename,
+        [op],
+        revision=revision,
+        rationale=rationale,
+        # `doc` commands are not `_DefsCommand`, so there is no parked
+        # `--dry-run` to inherit; say so rather than reading another
+        # command's meta.
+        dry_run=False,
+    )