deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/impact.py

@@ -0,0 +1,382 @@
+"""``deepcell impact`` — what still needs review after a change.
+
+Mirrors ``backend/jingwei_api/routers/impact.py`` 1:1. A thin pass-through, so
+the CLI, the viewer and an agent get the same answer about what a change
+reached and what counted as material — the judgement lives once, in
+``src/core/impact``, and nothing here re-decides any of it.
+
+This replaces the six-command sequence `guide revise/premise-change` §2 taught
+by hand (`assumption impact`, `reasoning impact`, `relationships`, `cell-meta`
+and one `doc backlinks` per affected id). Those still work and still answer
+narrower questions; this answers the whole one in a single call, and is the
+only one that carries the impact through to the Document sections and Deck
+slides rather than stopping at the reasoning node.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_info, echo_success, output, print_plain
+
+from ._swapped_args import FileFirstCommand, FileFirstGroup
+
+#: How a precision reads to a person. The distinction is the reason an affected
+#: set stops being either too broad or incomplete, so it is spelled out rather
+#: than printed as a term of art.
+_PRECISION = {"exact": "uses this value", "row": "uses this row"}
+
+#: Kinds that reached a place without citing anything, so no precision phrase
+#: describes them. Named here rather than imported: `backend/` is not on the
+#: CLI's path, and this is a rendering choice about one line of output, not a
+#: second opinion about what the kind means.
+_NOT_A_REFERENCE = {"stale_literal"}
+
+#: `HEAD` or `HEAD~N`, the spelling `describe --lint --since` already takes.
+#: Case-insensitive: `head~1` reached the server as-is and came back a 422.
+_HEAD_REVISION = re.compile(r"^HEAD(?:~(\d+))?$", re.IGNORECASE)
+
+#: What the server accepts verbatim: a 7-64 character hex SHA.
+_SHA_REVISION = re.compile(r"^[0-9a-fA-F]{7,64}$")
+
+_SINCE_HELP = (
+    "The revision to compare from: a SHA from `deepcell log`, or HEAD~N for "
+    "the N-th commit before the workspace's newest (resolved through the log "
+    "here; the server takes a 7-64 character SHA only). Note the SHA before "
+    "you edit — a premise change is usually several commits, and HEAD~1 "
+    "reaches only the last of them."
+)
+
+
+def _resolve_revision(ctx: Ctx, slug: str, revision: str, option: str) -> str:
+    """Turn `HEAD~N` into the SHA the server insists on.
+
+    `option` is the flag the value came from (`--since` or `--revision`), so
+    the usage error names the one to fix.
+
+    The server rejects anything that is not a hex SHA, so the CLI resolves the
+    shorthand the same way a reader would by hand: the workspace log, newest
+    first, whichever file each commit touched — which is what git's `HEAD~N`
+    means on the linear `main` every workspace has. The file filter is left
+    off on purpose: `describe --lint --since HEAD~1` is git-native and counts
+    every commit, and two commands spelling `HEAD~1` as different commits
+    would be worse than one spelling it only as a SHA.
+    """
+    match = _HEAD_REVISION.match(revision)
+    if match is None:
+        if _SHA_REVISION.match(revision):
+            return revision
+        # Anything else would round-trip to the server as a 422 in
+        # pydantic's words; say what the two accepted spellings are here.
+        raise click.BadParameter(
+            f"{revision!r} is neither a SHA (7-64 hex characters, from "
+            "`deepcell log`) nor HEAD~N.",
+            param_hint=option,
+        )
+    depth = int(match.group(1) or 0)
+    commits = ctx.client.get(
+        f"/workspaces/{slug}/versions", params={"max_count": depth + 1},
+    )
+    if not isinstance(commits, list) or len(commits) <= depth:
+        raise click.BadParameter(
+            f"{revision} is past the start of this workspace's history "
+            f"({len(commits) if isinstance(commits, list) else 0} commit(s)). "
+            "Pass a SHA from `deepcell log`.",
+            param_hint=option,
+        )
+    return commits[depth]["sha"]
+
+
+@click.group(cls=FileFirstGroup)
+def impact() -> None:
+    """What a change reached, and what still needs review."""
+
+
+@impact.command("show", cls=FileFirstCommand)
+@click.argument("filename")
+@click.option("--since", "base_revision", required=True, help=_SINCE_HELP)
+@click.option(
+    "--revision", default=None,
+    help="The revision to compare to (a SHA or HEAD~N). Defaults to the "
+         "working tree.",
+)
+@click.option(
+    "--threshold", type=float, default=None,
+    help=(
+        "Relative move at or above which a value change is material. "
+        "Defaults to the built-in 1%."
+    ),
+)
+@click.option(
+    "--include-reviewed", is_flag=True, default=False,
+    help="Also show items somebody has already marked reviewed.",
+)
+@pass_ctx
+def show(
+    ctx: Ctx,
+    filename: str,
+    base_revision: str,
+    revision: str | None,
+    threshold: float | None,
+    include_reviewed: bool,
+) -> None:
+    """List every place that may need review after a change.
+
+    Run it AFTER the edit lands: it compares two revisions, so before the
+    edit there is nothing to compare. Every item prints its `locator` and a
+    ready-to-paste `impact review` line — the review command needs both the
+    surface and the locator, and this is the only place they are printed.
+
+    Same-file only. Inverting cross-file links would mean scanning every
+    .deepcell in the workspace, which has no index and would undercount while
+    looking authoritative — so the scope is printed rather than assumed.
+    """
+    slug = ctx.require_workspace()
+    body = {
+        "workspace_slug": slug,
+        "source_filename": filename,
+        "base_revision": _resolve_revision(ctx, slug, base_revision, "--since"),
+        "include_reviewed": include_reviewed,
+    }
+    if revision is not None:
+        body["revision"] = _resolve_revision(ctx, slug, revision, "--revision")
+    if threshold is not None:
+        body["threshold"] = threshold
+
+    data = ctx.client.post("/impact", json=body)
+    if ctx.fmt != "plain":
+        output(data, ctx.fmt)
+        return
+
+    items = data.get("items", [])
+    # A created file whose queue somebody has WORKED THROUGH is aligned in the
+    # ordinary sense, and saying it "holds nothing to review" would deny the
+    # review that just happened — on a payload whose own `reviewed` counts it.
+    never_reviewed = not data.get("reviewed")
+    if not items:
+        if data.get("base_absent") and never_reviewed:
+            # `--since` named a revision older than the file itself, and the
+            # new file cites nothing a reader has to judge. "Everything is
+            # aligned" would credit a re-check that never had anything to do.
+            echo_success(
+                f"{filename} did not exist at that revision — this change "
+                f"created it, and it holds nothing to review."
+            )
+        else:
+            echo_success("Everything is aligned.")
+        _print_summary(data.get("summary") or {})
+        return
+
+    counts = data.get("counts") or {}
+    tally = " · ".join(f"{surface} {n}" for surface, n in sorted(counts.items()))
+    echo_info(f"{len(items)} place(s) need review — {tally}")
+    if data.get("base_absent") and never_reviewed:
+        # Every place is listed because the file is new, not because a change
+        # reached it. Without this the count reads as damage. Dropped once
+        # anything has been reviewed, when the claim stops being true.
+        print_plain(
+            f"{filename} did not exist at that revision — this change created "
+            f"it, so nothing here has been reviewed yet."
+        )
+    print_plain(f"scope: {data.get('scope', 'this file only')}")
+    print_plain("")
+
+    for item in items:
+        marker = "!" if item["state"] == "unresolved" else "·"
+        agent = " [agent can help]" if item.get("agent_eligible") else ""
+        print_plain(f"{marker} {item['surface'].upper()}  {item['display']}{agent}")
+        print_plain(f"    {item['cause']['summary']}")
+        if item["kind"] in _NOT_A_REFERENCE:
+            # Every phrase in `_PRECISION` describes how a *citation* addresses
+            # what moved, and these kinds are not citations — the text spells
+            # the number out. "Uses this value" beside "the text writes 200.75
+            # out as a literal" contradicts itself in two consecutive lines.
+            print_plain(f"    {item['gate_reason']}")
+        else:
+            print_plain(
+                f"    {_PRECISION.get(item['precision'], item['precision'])}"
+                f" — {item['gate_reason']}"
+            )
+        if item.get("path"):
+            # "Why is this affected?" — the nodes the change travelled through.
+            print_plain(f"    via {' -> '.join(item['path'])}")
+        print_plain(f"    key {item['item_key']}")
+        print_plain(f"    locator {item['locator']}")
+        # The next command, spelled out. `impact review` needs the surface and
+        # the locator as well as the key, and nothing else prints the locator
+        # — without this line the listing could not be acted on from its own
+        # output. A broken reference gets no review line because the server
+        # refuses one: it is rebound, not reviewed.
+        if item["state"] == "unresolved":
+            print_plain("    rebind the reference; a review does not clear it")
+        else:
+            print_plain(f"    review: {_review_line(filename, item)}")
+        print_plain("")
+
+    unresolved = data.get("unresolved", 0)
+    if unresolved:
+        # Said out loud because it is the one thing that stops this file being
+        # aligned however many paragraphs get confirmed.
+        echo_info(
+            f"{unresolved} unresolved reference(s) — these need a rebind, "
+            "not a review."
+        )
+
+
+@impact.command("review", cls=FileFirstCommand)
+@click.argument("filename")
+@click.argument("item_key")
+@click.option(
+    "--surface", required=True,
+    help="The surface the item is on, as `impact show` prints it.",
+)
+@click.option(
+    "--locator", required=True,
+    help="The item's address — the `locator` line `impact show` prints.",
+)
+@click.option(
+    "--outcome", type=click.Choice(["confirmed", "revised"]), default="confirmed",
+    help="confirmed: it still reads correctly. revised: it was rewritten.",
+)
+@click.option(
+    "--kind", default=None,
+    help="The item's kind. An unresolved one is refused: it needs a rebind.",
+)
+@pass_ctx
+def review(
+    ctx: Ctx, filename: str, item_key: str, surface: str, locator: str,
+    outcome: str, kind: str | None,
+) -> None:
+    """Mark one item reviewed — the marker disappears.
+
+    `impact show` prints this command ready to paste under every item, key,
+    surface and locator filled in. It comes back on its own if the same place
+    is reached by a *new* change: the key folds in what changed, not only
+    where.
+
+    `--kind` is optional and worth passing: a `broken_ref` is refused outright,
+    rather than recorded and then ignored on the next read because a review
+    decision cannot rebind an address.
+    """
+    ctx.client.post("/impact/review", json={
+        "workspace_slug": ctx.require_workspace(),
+        "source_filename": filename,
+        "item_key": item_key,
+        "surface": surface,
+        "locator": locator,
+        "outcome": outcome,
+        **({"kind": kind} if kind else {}),
+    })
+    echo_success(f"Reviewed ({outcome}): {item_key}")
+
+
+@impact.command("apply", cls=FileFirstCommand)
+@click.argument("filename")
+@click.argument("item_key")
+@click.option("--surface", required=True, help="The surface the item is on.")
+@click.option("--locator", required=True, help="The item's address.")
+@click.option("--op", required=True, help="The reasoning op to apply.")
+@click.option("--target-id", required=True, help="The Claim or Assumption it addresses.")
+@click.option(
+    "--payload", default=None,
+    help="The op's fields, as JSON. Omit for an op that needs none.",
+)
+@click.option(
+    "--new-claim", default=None,
+    help="JSON for the replacement Claim. Required by supersede_claim.",
+)
+@click.option(
+    "--new-assumption", default=None,
+    help="JSON for the replacement Assumption. Required by supersede_assumption.",
+)
+@click.option(
+    "--expected-revision", default=None,
+    help="The revision you read at. A newer document is a 409 rather than an "
+         "overwrite.",
+)
+@pass_ctx
+def apply(
+    ctx: Ctx, filename: str, item_key: str, surface: str, locator: str,
+    op: str, target_id: str, payload: str | None, new_claim: str | None,
+    new_assumption: str | None, expected_revision: str | None,
+) -> None:
+    """Apply one reviewed fix, and record it as `revised`.
+
+    The write and the ledger row are one decision. Applied and unrecorded, the
+    item comes back on the next read as though nothing happened and you fix it
+    twice.
+
+    Only reasoning ops, and only the ones a review may make: no `delete_*`
+    (supersession preserves history a delete destroys) and no
+    `set_conclusion` / `set_key_question` (reframing the document is the
+    author's call). Anything else is refused, whatever proposed it.
+    """
+    def _json(flag: str, raw: str | None):
+        if raw is None:
+            return None
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise click.BadParameter(f"{flag} is not valid JSON: {exc}")
+
+    data = ctx.client.post("/impact/apply", json={
+        "workspace_slug": ctx.require_workspace(),
+        "source_filename": filename,
+        "item_key": item_key,
+        "surface": surface,
+        "locator": locator,
+        "op": op,
+        "target_id": target_id,
+        "payload": _json("--payload", payload) or {},
+        **({"new_claim": _json("--new-claim", new_claim)} if new_claim else {}),
+        **({"new_assumption": _json("--new-assumption", new_assumption)}
+           if new_assumption else {}),
+        **({"expected_revision": expected_revision} if expected_revision else {}),
+    })
+    echo_success(f"Applied and recorded as revised: {item_key}")
+    if data.get("revision"):
+        echo_info(f"Now at {data['revision']}.")
+
+
+@impact.command("reopen", cls=FileFirstCommand)
+@click.argument("filename")
+@click.argument("item_key")
+@pass_ctx
+def reopen(ctx: Ctx, filename: str, item_key: str) -> None:
+    """Undo one review decision."""
+    data = ctx.client.post("/impact/reopen", json={
+        "workspace_slug": ctx.require_workspace(),
+        "source_filename": filename,
+        "item_key": item_key,
+    })
+    if data.get("removed"):
+        echo_success(f"Reopened: {item_key}")
+    else:
+        echo_info(f"Nothing to reopen: {item_key} was not marked reviewed.")
+
+
+def _review_line(filename: str, item: dict) -> str:
+    """The `impact review` invocation that clears `item`, shell-quoted."""
+    return (
+        f"deepcell impact review {shlex.quote(filename)} {item['item_key']}"
+        f" --surface {item['surface']} --locator {shlex.quote(item['locator'])}"
+        f" --kind {item['kind']} --outcome confirmed"
+    )
+
+
+def _print_summary(summary: dict) -> None:
+    if not summary:
+        return
+    lines = [
+        (summary.get("updated_automatically", 0), "value(s) updated automatically"),
+        (summary.get("confirmed", 0), "item(s) confirmed"),
+        (summary.get("revised", 0), "item(s) revised"),
+    ]
+    for count, label in lines:
+        if count:
+            print_plain(f"  {count} {label}")

deepcell_cli/commands/import_cmd.py

@@ -0,0 +1,208 @@
+"""``deepcell import`` — import xlsx/csv files into .deepcell documents."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from deepcell_cli.commands._datatypes import warn_unrecognized_data_type
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_success, echo_warning
+
+
+def _load_json_arg(value: str) -> list:
+    """Load JSON from a string or file path."""
+    path = Path(value)
+    try:
+        is_file = path.exists()
+    except OSError:
+        # `Path.exists()` raises ENAMETOOLONG on an inline payload longer
+        # than a path component, which read as "Import failed" for any items
+        # list past a few entries. A string that cannot be a path is JSON.
+        is_file = False
+    if is_file:
+        return json.loads(path.read_text())
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as e:
+        raise click.ClickException(f"Invalid JSON: {e}")
+
+
+@click.command("import")
+@click.argument("file", type=click.Path(exists=True))
+@click.option("--items", required=True, help="Items JSON string or path to JSON file.")
+@click.option("--contexts", required=True, help="Contexts JSON string or path to JSON file.")
+@click.option("--name", default=None, help="Name for the .deepcell file (default: input filename).")
+@click.option("--workspace", default=None, help="Target workspace slug.")
+@click.option("--aggregations", default=None, help="Aggregation rules JSON string or path to JSON file.")
+@click.option("--keep-raw", is_flag=True, default=False, help="Store raw values alongside aggregated results.")
+@pass_ctx
+def import_cmd(
+    ctx: Ctx,
+    file: str,
+    items: str,
+    contexts: str,
+    name: str | None,
+    workspace: str | None,
+    aggregations: str | None,
+    keep_raw: bool,
+) -> None:
+    """Import an xlsx or csv file into a .deepcell document.
+
+    Requires structured analysis as JSON: items (with row numbers) and
+    contexts (with column letters). The cell map is auto-generated from
+    the item rows × context columns cross-product. The result is saved as
+    NAME.deepcell (--name, default: the input file's stem) and replaces a
+    file of that name — import creates; it does not merge into an existing
+    document.
+
+    Use --aggregations to specify custom mapping rules that aggregate
+    source values into target coordinates. Only aggregated results are
+    stored unless --keep-raw is also provided.
+
+    \b
+    An items entry takes:
+      id, name, level            required
+      parent_id                  hierarchy
+      data_type                  monetary | percentage | ratio | quantity |
+                                 count | number | text | date — the set
+                                 `deepcell ref datatype` documents. Anything
+                                 else is stored verbatim with a warning and
+                                 renders as plain text.
+      scale, currency            REQUIRED on a monetary item (house rule R7) —
+                                 scale is the power of ten the values are
+                                 stated in (3 = thousands), currency an ISO
+                                 4217 code. Omit them and every monetary row
+                                 fails `describe --lint`, because 4200 could
+                                 be dollars, thousands or millions.
+      row, sheet                 where the data lives in the workbook. A
+                                 multi-sheet workbook needs `sheet` on EVERY
+                                 item: one without it is read from the first
+                                 item's sheet (else Sheet1) — silently the
+                                 wrong tab, or a skipped cell.
+
+    \b
+    A contexts entry takes:
+      id, name, period_type      required (annual | quarterly | monthly | custom)
+      status                     which status this column belongs to
+      status_archetype           what that status IS (R13): actual |
+                                 preliminary | restated | estimate | guidance
+                                 | consensus | forecast | budget | plan |
+                                 target. `deepcell ref status` lists them.
+      state                      closed | open | future (R13) — period kinds only
+      start_date, end_date       ISO dates
+      column                     workbook column letter — a letter only, no
+                                 sheet. Every context column is read on every
+                                 item's sheet, so one import carries ONE column
+                                 layout. A tab whose periods sit in other
+                                 columns is a second pass into the same file
+                                 via `deepcell edit FILE --batch`, never a
+                                 second import under another name (rule R3).
+      kind                       period (default) or a non-temporal label
+
+    Everything R7 and R13 require can be stated at import time. Leaving them
+    out means a follow-up `defs update-item` per item and `defs update-context`
+    per context before the document is rule-clean.
+
+    Provenance: one <Source kind="workbook"> with a <Cites at="sheet:TAB!B5">
+    row per mapped cell (item row × context column). `deepcell guide ingest/tabular` covers what to do
+    after that.
+    """
+    file_path = Path(file)
+    if name is None:
+        name = file_path.stem
+
+    # Parse JSON arguments
+    items_data = _load_json_arg(items)
+    contexts_data = _load_json_arg(contexts)
+
+    # Same check `defs add-item --data-type` runs. The backend stores the
+    # type verbatim, so a typo (`moneytary`) or the retired `string` would
+    # otherwise land in the file and every formatter would silently fall back
+    # to its default. A warning, not a rejection — the vocabulary is open.
+    if isinstance(items_data, list):
+        for index, entry in enumerate(items_data):
+            if not isinstance(entry, dict):
+                continue
+            message = warn_unrecognized_data_type(entry.get("data_type"))
+            if message:
+                label = entry.get("id") or f"items[{index}]"
+                echo_warning(f"{label}: {message}")
+
+    fields: dict[str, str] = {
+        "items": json.dumps(items_data),
+        "contexts": json.dumps(contexts_data),
+        "name": name,
+        "workspace_slug": workspace or ctx.require_workspace(),
+    }
+
+    if aggregations:
+        agg_data = _load_json_arg(aggregations)
+        fields["aggregations"] = json.dumps(agg_data)
+
+    if keep_raw:
+        fields["keep_raw"] = "true"
+
+    # Send to backend
+    try:
+        result = ctx.client.post_multipart(
+            "/import",
+            file_path=str(file_path),
+            file_name=file_path.name,
+            fields=fields,
+        )
+    except click.ClickException:
+        raise
+    except Exception as e:
+        raise click.ClickException(f"Import failed: {e}")
+
+    skipped = result.get("skipped_values") or []
+
+    # Handle JSON output format
+    if ctx.fmt == "json":
+        click.echo(json.dumps(result, indent=2))
+        if skipped:
+            raise click.exceptions.Exit(1)
+        return
+
+    # Display result
+    summary = result.get("summary", {})
+    dest = result.get("file_path", name)
+    ws = result.get("workspace", "default")
+
+    echo_success(f"Imported {file_path.name} -> {dest}")
+    click.echo(f"  Workspace: {ws}", err=True)
+    click.echo(f"  Items: {summary.get('items', 0)}", err=True)
+    click.echo(f"  Contexts: {summary.get('contexts', 0)}", err=True)
+    click.echo(f"  Values: {summary.get('values', 0)}", err=True)
+
+    fc = summary.get("formulas_converted", 0)
+    fw = summary.get("formulas_warnings", 0)
+    if fc or fw:
+        click.echo(f"  Formulas: {fc} converted, {fw} warnings", err=True)
+
+    # Show warnings
+    for w in result.get("warnings", []):
+        echo_warning(f"{w.get('sheet', '')}:{w.get('cell', '')} -- {w.get('issue', '')}")
+
+    for s in skipped:
+        echo_warning(f"Skipped {s.get('sheet', '')}:{s.get('cell', '')} ({s.get('item_id', '')}) -- {s.get('issue', '')}")
+
+    if aggregations and not keep_raw:
+        echo_warning(
+            "Raw source values were not stored. "
+            "Use --keep-raw to retain source values alongside aggregated results."
+        )
+
+    if skipped:
+        # Skipped cells = data missing from the imported model. The import is
+        # committed, but it must not read as a clean success (same contract as
+        # `variant merge`, which exits 1 on had_data_loss).
+        echo_warning(
+            f"{len(skipped)} source value(s) skipped — the imported model is "
+            "missing data; fix the cells above and re-import, or fill them "
+            "with `deepcell edit`"
+        )
+        raise click.exceptions.Exit(1)