deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/ingest.py

@@ -0,0 +1,110 @@
+"""``deepcell ingest`` — pull external filings into extractable data.
+
+Thin pass-through to the Jingwei ``/ingest`` endpoints. Currently the ``cn``
+group covers cninfo (巨潮资讯网) A-share annual / interim reports:
+
+\b
+    deepcell ingest cn search "贵州茅台"
+    deepcell ingest cn filings 600519 --type annual
+    deepcell ingest cn statements <pdf_url>
+    deepcell ingest cn extract <pdf_url> --statement 合并利润表
+
+The typical flow: search → filings (copy a PDF url) → statements (find the
+page) → extract (rows + canonical item ids + a #page deep link). Feed the
+result to a modeler / `deepcell write` per `deepcell guide cn-extraction`.
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_warning, output, print_plain
+
+
+@click.group()
+def ingest() -> None:
+    """Pull external filings into extractable statement data."""
+
+
+@ingest.group()
+def cn() -> None:
+    """cninfo (A-share) filings — Shanghai / Shenzhen / Beijing exchanges."""
+
+
+@cn.command("search")
+@click.argument("keywords")
+@pass_ctx
+def cn_search(ctx: Ctx, keywords: str) -> None:
+    """Resolve a 6-digit code, company name (中文简称), or pinyin."""
+    data = ctx.client.get("/ingest/cn/search", params={"keywords": keywords})
+    output(data.get("matches", data), ctx.fmt)
+
+
+@cn.command("filings")
+@click.argument("code")
+@click.option("--type", "filing_type", default="annual",
+              help="annual | interim | semiannual | q1 | q3")
+@click.option("--count", default=5, type=click.IntRange(1, 30),
+              help="number of reports (1-30)")
+@pass_ctx
+def cn_filings(ctx: Ctx, code: str, filing_type: str, count: int) -> None:
+    """List annual / interim reports with PDF permalinks."""
+    data = ctx.client.get(
+        "/ingest/cn/filings",
+        params={"code": code, "filing_type": filing_type, "count": count},
+    )
+    output(data.get("filings", data), ctx.fmt)
+
+
+@cn.command("statements")
+@click.argument("pdf_url")
+@pass_ctx
+def cn_statements(ctx: Ctx, pdf_url: str) -> None:
+    """Locate the financial statements inside a report PDF (page + scale)."""
+    data = ctx.client.get("/ingest/cn/statements", params={"pdf_url": pdf_url})
+    output(data.get("statements", data), ctx.fmt)
+
+
+@cn.command("extract")
+@click.argument("pdf_url")
+@click.option("--statement", default="合并利润表",
+              help="Chinese heading or income | balance | cash_flow")
+@click.option(
+    "--persist/--no-persist",
+    "persist",
+    default=True,
+    help="Mirror the source PDF into DeepCell storage and return a durable "
+         "`source_page_url` to record as the <Source> <Locator>. --no-persist "
+         "skips the mirror (faster, but the only url you get back is the "
+         "volatile cninfo link).",
+)
+@pass_ctx
+def cn_extract(ctx: Ctx, pdf_url: str, statement: str, persist: bool) -> None:
+    """Extract one statement's table — rows, canonical items, #page deep link."""
+    data = ctx.client.get(
+        "/ingest/cn/extract",
+        # Key matches the `persist` query param on GET /ingest/cn/extract.
+        params={"pdf_url": pdf_url, "statement": statement, "persist": persist},
+    )
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+    # Human-readable: the markdown table plus the provenance lines. The mirror
+    # url (source_page_url) is the deepcell-hosted copy to record as <Url>.
+    mirror = data.get("source_page_url") or data.get("deep_link")
+    mirror_error = data.get("mirror_error")
+    if mirror_error:
+        # Without this the volatile cninfo link is printed as the durable
+        # `<Url>` to record, indistinguishable from a real mirror.
+        echo_warning(
+            f"{mirror_error} The 'Source <Url>' below is the ORIGINAL cninfo "
+            f"link, which may move — re-run to retry mirroring."
+        )
+    print_plain(
+        f"Statement: {data.get('statement')}  (page {data.get('page')})\n"
+        f"Source <Url>:   {mirror}\n"
+        f"Original (cninfo): {data.get('original_url') or data.get('deep_link')}\n"
+        f"Scale: 10^{data.get('scale')}  Currency: {data.get('currency')}\n\n"
+        f"{data.get('markdown', '')}"
+    )

deepcell_cli/commands/merge.py

@@ -0,0 +1,399 @@
+"""Merge commands: preview, apply, and convenience resolve for .deepcell files.
+
+Provides semantic three-way merge for .deepcell XML files using the backend
+merge service. Works both standalone and as part of the pull conflict workflow.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_error, echo_info, echo_success, echo_warning
+from deepcell_cli.sync_state import (
+    FileChecksum,
+    compute_local_hash,
+    find_sync_root,
+    load_sync_state,
+    save_sync_state,
+)
+
+
+# -- Helpers -------------------------------------------------------------------
+
+
+def _read_local(root: Path, filename: str) -> str:
+    """Read a file from the sync root."""
+    path = root / filename
+    if not path.exists():
+        raise click.ClickException(f"File not found: {filename}")
+    return path.read_text(encoding="utf-8")
+
+
+def _download_file(client, slug: str, filename: str, *, revision: str | None = None) -> str:
+    """Download a file from the workspace, optionally at a specific revision."""
+    params = {"revision": revision} if revision else None
+    data = client.get(f"/workspaces/{slug}/files/{filename}", params=params)
+    if isinstance(data, dict) and "content" in data:
+        return data["content"]
+    return str(data)
+
+
+def _show_conflicts(conflicts: list[dict]) -> None:
+    """Display conflict details to stderr."""
+    for c in conflicts:
+        item = c.get("item_ref", "?")
+        ctx = c.get("context_ref", "")
+        status = c.get("status_ref") or ""
+        ctype = c.get("type", "value")
+        ours = c.get("ours", "")
+        theirs = c.get("theirs", "")
+        base = c.get("base", "")
+        coords = ", ".join(p for p in (ctx, status) if p)
+        label = f"{item}[{coords}]" if coords else item
+        echo_warning(f"  {ctype}: {label}  base={base}  ours={ours}  theirs={theirs}")
+
+
+def echo_merge_data_loss(result: dict) -> bool:
+    """Report items/values the merge could not carry over.
+
+    ``success`` is computed from the conflict count alone and cannot reflect
+    an apply-time drop, so a merge that silently lost an item still comes back
+    ``success=True``. Returns True when anything was dropped, so callers can
+    keep the ``.local`` backup and exit non-zero.
+    """
+    if not isinstance(result, dict):
+        return False
+    items = list(result.get("items_not_merged") or [])
+    values = list(result.get("values_not_merged") or [])
+    if not items and not values:
+        return False
+    if items:
+        echo_warning(
+            f"{len(items)} item(s) could NOT be merged and are missing from the "
+            f"result: {', '.join(items)}"
+        )
+    if values:
+        echo_warning(
+            f"{len(values)} value(s) could NOT be written to the merged "
+            f"document: {', '.join(values)}"
+        )
+    echo_warning(
+        "Re-apply them by hand — the merge is incomplete despite reporting success."
+    )
+    return True
+
+
+def _update_checksum(root: Path, state, filename: str, server_content: str) -> None:
+    """Re-baseline a merged file against what the SERVER holds.
+
+    *server_content* is `theirs` — the content the merge was performed
+    against, which is still what is committed. The merge result exists only on
+    disk until it is pushed, so baselining it against the merged content made
+    `push` report "Nothing to push" and `status` report Clean, stranding the
+    resolved merge with no command left to reveal it.
+    """
+    if filename in state.file_checksums:
+        state.file_checksums[filename] = FileChecksum(
+            git_sha=state.file_checksums[filename].git_sha,
+            local_hash=compute_local_hash(server_content),
+        )
+        save_sync_state(root, state)
+
+
+# -- merge group ---------------------------------------------------------------
+
+
+@click.group()
+def merge() -> None:
+    """Merge .deepcell files with semantic three-way merge.
+
+    \b
+    Resolve sync conflicts:
+      deepcell merge resolve model.deepcell            # auto-merge, show conflicts
+      deepcell merge resolve model.deepcell --ours     # keep all local values
+      deepcell merge resolve model.deepcell --theirs   # take all remote values
+
+    \b
+    Power-user subcommands:
+      deepcell merge preview model.deepcell            # preview merge result
+      deepcell merge apply <session-id> --resolve ours # resolve by session ID
+    """
+
+
+# -- merge resolve (convenience) -----------------------------------------------
+
+
+@merge.command()
+@click.argument("filename")
+@click.option("--ours", "strategy", flag_value="ours", help="Resolve all conflicts with local values.")
+@click.option("--theirs", "strategy", flag_value="theirs", help="Resolve all conflicts with remote values.")
+@pass_ctx
+def resolve(ctx: Ctx, filename: str, strategy: str | None) -> None:
+    """Resolve a sync conflict for a .deepcell file.
+
+    After `deepcell pull` creates a conflict (file.deepcell.local), use this
+    command to merge or pick a side. --ours and --theirs are wholesale: they
+    take that side for *every* conflicting value, so prefer the bare
+    auto-merge and resolve what it reports.
+
+    \b
+      deepcell merge resolve model.deepcell            # try auto-merge
+      deepcell merge resolve model.deepcell --ours     # keep local values
+      deepcell merge resolve model.deepcell --theirs   # take remote values
+    """
+    root = find_sync_root()
+    if root is None:
+        raise click.ClickException(
+            "Not inside a synced workspace. Run `deepcell clone <slug>` first."
+        )
+
+    state = load_sync_state(root)
+    client = ctx.client
+    slug = state.workspace_slug
+
+    local_backup = root / f"{filename}.local"
+    if not local_backup.exists():
+        raise click.ClickException(
+            f"No conflict found for {filename} (no {filename}.local file). "
+            "Conflicts are created by `deepcell pull` when both sides change a file."
+        )
+
+    # .local = ours (original local), main file = theirs (remote)
+    ours_xml = local_backup.read_text(encoding="utf-8")
+    theirs_xml = (root / filename).read_text(encoding="utf-8")
+
+    # Fetch base version from last sync point
+    if not state.last_sync_sha:
+        raise click.ClickException(
+            "Cannot determine merge base: no last_sync_sha in sync state."
+        )
+
+    try:
+        base_xml = _download_file(client, slug, filename, revision=state.last_sync_sha)
+    except Exception as exc:
+        raise click.ClickException(
+            f"Failed to fetch base version at {state.last_sync_sha[:8]}: {exc}"
+        ) from exc
+
+    # Call merge preview
+    try:
+        result = client.post("/merge/preview", json={
+            "base_xml": base_xml,
+            "ours_xml": ours_xml,
+            "theirs_xml": theirs_xml,
+            "filename": filename,
+        })
+    except Exception as exc:
+        raise click.ClickException(f"Merge API call failed: {exc}") from exc
+
+    if result.get("success") and result.get("merged_xml"):
+        # Clean merge — write result and remove .local
+        (root / filename).write_text(result["merged_xml"], encoding="utf-8")
+        _update_checksum(root, state, filename, theirs_xml)
+        auto_count = result.get("auto_resolved_count", 0)
+        if echo_merge_data_loss(result):
+            # Keep the .local backup: it is the only surviving copy of what
+            # the merge dropped.
+            echo_warning(
+                f"Merged {filename} ({auto_count} change(s) auto-resolved) but data "
+                f"was lost — '{filename}.local' kept so you can recover it"
+            )
+            raise click.exceptions.Exit(1)
+        local_backup.unlink()
+        echo_success(f"Merged {filename} ({auto_count} change(s) auto-resolved)")
+        return
+
+    # Has conflicts
+    conflicts = result.get("conflicts", [])
+    session_id = result.get("merge_session_id")
+
+    if not strategy:
+        echo_error(f"{len(conflicts)} conflict(s) in {filename}:")
+        _show_conflicts(conflicts)
+        echo_info("Resolve with --ours or --theirs, or use `deepcell merge apply`.")
+        if session_id:
+            echo_info(f"Session ID: {session_id}")
+        raise SystemExit(1)
+
+    # Resolve all conflicts with chosen strategy
+    if not session_id:
+        raise click.ClickException("No merge session ID returned. Try again.")
+
+    resolutions = {c["conflict_id"]: strategy for c in conflicts}
+    try:
+        resolved = client.post("/merge/resolve", json={
+            "merge_session_id": session_id,
+            "resolutions": resolutions,
+        })
+    except Exception as exc:
+        raise click.ClickException(f"Merge resolve failed: {exc}") from exc
+
+    if resolved.get("success") and resolved.get("merged_xml"):
+        (root / filename).write_text(resolved["merged_xml"], encoding="utf-8")
+        _update_checksum(root, state, filename, theirs_xml)
+        if echo_merge_data_loss(resolved):
+            echo_warning(
+                f"Resolved {len(conflicts)} conflict(s) with --{strategy} but data was "
+                f"lost — '{filename}.local' kept so you can recover it"
+            )
+            raise click.exceptions.Exit(1)
+        local_backup.unlink()
+        echo_success(f"Merged {filename} (resolved {len(conflicts)} conflict(s) with --{strategy})")
+    else:
+        remaining = resolved.get("remaining_conflicts", 0)
+        echo_error(f"{remaining} conflict(s) still unresolved in {filename}")
+        _show_conflicts(resolved.get("conflicts", []))
+        raise SystemExit(1)
+
+
+# -- merge preview -------------------------------------------------------------
+
+
+@merge.command()
+@click.argument("filename")
+@click.option("--base", "base_rev", default=None, help="Base revision SHA (defaults to last_sync_sha).")
+@click.option("--theirs-rev", default=None, help="Revision for theirs (defaults to HEAD).")
+@pass_ctx
+def preview(ctx: Ctx, filename: str, base_rev: str | None, theirs_rev: str | None) -> None:
+    """Preview a three-way merge for a .deepcell file.
+
+    \b
+    deepcell merge preview model.deepcell
+    deepcell merge preview model.deepcell --base abc1234
+    """
+    root = find_sync_root()
+    if root is None:
+        raise click.ClickException("Not inside a synced workspace.")
+
+    state = load_sync_state(root)
+    client = ctx.client
+    slug = state.workspace_slug
+
+    # Ours = local file
+    ours_xml = _read_local(root, filename)
+
+    # Base = file at base_rev or last_sync_sha
+    base_sha = base_rev or state.last_sync_sha
+    if not base_sha:
+        raise click.ClickException("No base revision available. Specify --base <sha>.")
+
+    try:
+        base_xml = _download_file(client, slug, filename, revision=base_sha)
+    except Exception as exc:
+        raise click.ClickException(f"Failed to fetch base at {base_sha[:8]}: {exc}") from exc
+
+    # Theirs = file at theirs_rev or HEAD, on the branch you are actually on.
+    # Reading main's HEAD while a variant is checked out compares against the
+    # wrong branch: conflicts that don't exist on your branch, or a clean
+    # merge that isn't. (Base stays pinned to a SHA via the main route —
+    # commit SHAs are branch-independent and the variant route ignores
+    # `revision`.)
+    from deepcell_cli.commands.sync import _download_branch_file
+
+    try:
+        theirs_xml = _download_branch_file(
+            client, slug, filename,
+            variant=state.active_variant, revision=theirs_rev,
+        )
+    except Exception as exc:
+        raise click.ClickException(f"Failed to fetch theirs: {exc}") from exc
+
+    # Call merge preview
+    result = client.post("/merge/preview", json={
+        "base_xml": base_xml,
+        "ours_xml": ours_xml,
+        "theirs_xml": theirs_xml,
+        "filename": filename,
+    })
+
+    auto_count = result.get("auto_resolved_count", 0)
+    conflict_count = result.get("conflict_count", 0)
+    echo_info(f"Auto-resolved: {auto_count}  Conflicts: {conflict_count}")
+
+    if result.get("success"):
+        lossy = echo_merge_data_loss(result)
+        echo_success("Clean merge — no conflicts.")
+        if result.get("merged_xml"):
+            click.echo(result["merged_xml"])
+        if lossy:
+            raise click.exceptions.Exit(1)
+    else:
+        conflicts = result.get("conflicts", [])
+        _show_conflicts(conflicts)
+        session_id = result.get("merge_session_id")
+        if session_id:
+            echo_info(f"Session ID: {session_id}")
+            echo_info("Resolve with: deepcell merge apply <session-id> --resolve ours|theirs")
+        # Exit nonzero so scripts can branch on "would this merge cleanly?"
+        # (consistent with `merge resolve`/`apply` and `describe --lint`).
+        raise click.exceptions.Exit(1)
+
+
+# -- merge apply ---------------------------------------------------------------
+
+
+@merge.command()
+@click.argument("session_id")
+@click.option(
+    "--resolve",
+    "strategy",
+    type=click.Choice(["ours", "theirs"]),
+    required=True,
+    help="Resolution strategy for all conflicts.",
+)
+@click.option("--file", "filename", default=None, help="Write merged result to this local file.")
+@pass_ctx
+def apply(ctx: Ctx, session_id: str, strategy: str, filename: str | None) -> None:
+    """Apply conflict resolutions to a pending merge session.
+
+    \b
+    deepcell merge apply <session-id> --resolve ours
+    deepcell merge apply <session-id> --resolve theirs --file model.deepcell
+    """
+    client = ctx.client
+
+    try:
+        result = client.post("/merge/resolve", json={
+            "merge_session_id": session_id,
+            "resolutions": {"*": strategy},
+        })
+    except Exception as exc:
+        raise click.ClickException(f"Merge resolve failed: {exc}") from exc
+
+    if result.get("success") and result.get("merged_xml"):
+        lossy = echo_merge_data_loss(result)
+        if filename:
+            root = find_sync_root()
+            if root:
+                target = root / filename
+                # Read before overwriting: `pull` left `theirs` in the tracked
+                # file, and that is what the new baseline must be.
+                server_content = (
+                    target.read_text(encoding="utf-8") if target.exists() else ""
+                )
+                target.write_text(result["merged_xml"], encoding="utf-8")
+                state = load_sync_state(root)
+                _update_checksum(root, state, filename, server_content)
+                # Clean up .local — unless the merge dropped data, in which
+                # case the backup is the only copy of what was lost.
+                local_backup = root / f"{filename}.local"
+                if local_backup.exists() and not lossy:
+                    local_backup.unlink()
+                echo_success(f"Merged and written to {filename}")
+            else:
+                Path(filename).write_text(result["merged_xml"], encoding="utf-8")
+                echo_success(f"Merged and written to {filename}")
+        else:
+            # Output merged XML to stdout
+            click.echo(result["merged_xml"])
+            echo_success("Merge resolved successfully")
+        if lossy:
+            raise click.exceptions.Exit(1)
+    else:
+        remaining = result.get("remaining_conflicts", 0)
+        echo_error(f"{remaining} conflict(s) still unresolved")
+        _show_conflicts(result.get("conflicts", []))
+        raise SystemExit(1)