calkit-python 0.48.1__py3-none-any.whl → 0.48.2__py3-none-any.whl

calkit/cli/latex.py

@@ -10,6 +10,7 @@ import shutil
 import string
 import subprocess
 import sys
+from collections.abc import Callable
 from copy import deepcopy
 from pathlib import Path
 
@@ -189,6 +190,186 @@ def from_questions(
             json2latex.dump(command_name, values, f)
 
 
+@latex_app.command(name="from-markdown")
+def from_markdown(
+    md_path: Annotated[
+        str, typer.Argument(help="The Markdown file to build.")
+    ],
+    outputs: Annotated[
+        list[str],
+        typer.Option(
+            "--output",
+            "-o",
+            help="Where to write the PDF, or the LaTeX with a .tex "
+            "extension; can be given more than once.",
+        ),
+    ],
+    environment: Annotated[
+        str | None,
+        typer.Option(
+            "--environment",
+            "-e",
+            help="Environment to run pandoc and LaTeX in, e.g., one using "
+            "Calkit's LaTeX image, which includes both.",
+        ),
+    ] = None,
+    template_path: Annotated[
+        str | None, typer.Option("--template", help="Pandoc template.")
+    ] = None,
+    filters: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--filter", help="Pandoc Lua filter; can be given more than once."
+        ),
+    ] = None,
+    pandoc_args: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--pandoc-arg",
+            help="Another argument for pandoc; can be given more than once.",
+        ),
+    ] = None,
+    no_check: Annotated[
+        bool,
+        typer.Option("--no-check", help="Don't check the environment first."),
+    ] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Print commands.")
+    ] = False,
+) -> None:
+    """Build a Markdown file into a PDF with pandoc and LaTeX.
+
+    Value markers are filled from their results files, which keeps the
+    Markdown itself current too, and each value links to the question on
+    the project's hub whose evidence cites it. The template gets the Calkit
+    version and the project's URL as the ``calkit-version``,
+    ``project-url``, and ``project`` variables.
+    """
+    import calkit.docx
+    import calkit.markdown
+
+    def question_url(value: calkit.markdown.MarkdownValue) -> str | None:
+        # The question whose evidence cites this value, or failing that,
+        # the first to cite its file
+        if project_url is None:
+            return None
+        first = None
+        for n, q in enumerate(ck_info.get("questions") or [], start=1):
+            evidence = q.get("evidence") if isinstance(q, dict) else None
+            for ev in evidence or []:
+                if not isinstance(ev, dict) or ev.get("path") != value.path:
+                    continue
+                keys = [ev.get("key"), *(ev.get("values") or {}).values()]
+                if value.key in keys:
+                    return f"{project_url}/questions/{n}"
+                first = first or n
+        return f"{project_url}/questions/{first}" if first else None
+
+    def to_latex(tex_path: str) -> None:
+        # Images are pointed at from where the LaTeX is, by a filter that
+        # runs before the others, so they see the paths LaTeX will
+        build_dir = os.path.dirname(tex_path) or "."
+        os.makedirs(build_dir, exist_ok=True)
+        stem = Path(tex_path).stem
+        src_path = f"{build_dir}/{stem}.pandoc.md"
+        with open(src_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(
+                calkit.markdown.prepare_for_pdf(
+                    text, md_path, link=question_url
+                )
+            )
+        prefix = Path(os.path.relpath(md_dir, build_dir)).as_posix()
+        repoint = f"{build_dir}/{stem}.images.lua"
+        with open(repoint, "w", encoding="utf-8", newline="\n") as f:
+            f.write(calkit.markdown.image_prefix_filter(prefix))
+        args = [src_path, "-o", tex_path, "--standalone"]
+        if template_path is not None:
+            args += ["--template", template_path]
+        for path in [repoint, *(filters or [])]:
+            args += ["--lua-filter", path]
+        args += [f"--variable=calkit-version:{version}"]
+        if project_url is not None:
+            args += [
+                f"--variable=project-url:{project_url}",
+                f"--variable=project:{project_url.split('://', 1)[1]}",
+            ]
+        args += pandoc_args or []
+        if environment is not None:
+            cmd = _tex_cmd(
+                ["pandoc", *args], environment, no_check, verbose, dep="pandoc"
+            )
+        else:
+            pandoc = calkit.docx.find_pandoc()
+            if pandoc is None:
+                raise_error(
+                    "Pandoc is needed; name an environment that has it, "
+                    "e.g., one using Calkit's LaTeX image, or install it"
+                )
+            cmd = [pandoc, *args]
+        try:
+            subprocess.check_call(cmd)
+        except subprocess.CalledProcessError:
+            raise_error(f"Pandoc failed to convert {md_path}")
+
+    for output in outputs:
+        if not output.endswith((".pdf", ".tex")):
+            raise_error("Outputs must be .pdf or .tex files")
+    # Paths go into the build directory's, so they have to be the
+    # project's own
+    rel = os.path.relpath(md_path)
+    if rel == ".." or rel.startswith(".." + os.sep) or os.path.isabs(rel):
+        raise_error(f"{md_path} isn't in this project")
+    md_path = Path(rel).as_posix()
+    md_dir = os.path.dirname(md_path) or "."
+    ck_info = calkit.load_calkit_info()
+    project_url = None
+    if ck_info.get("owner") and ck_info.get("name"):
+        hub = str(ck_info.get("hub") or "calkit.io").rstrip("/")
+        if "://" not in hub:
+            hub = "https://" + hub
+        project_url = f"{hub}/{ck_info['owner']}/{ck_info['name']}"
+    # A local version's commit is the project's own, which isn't Calkit's
+    version = calkit.__version__.split("+")[0]
+    with open(md_path, encoding="utf-8") as f:
+        text = f.read()
+    try:
+        text, changed = calkit.markdown.set_values(text, md_path)
+    except calkit.markdown.MarkdownParseError as e:
+        raise_error(str(e))
+    if changed:
+        with open(md_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+    for output in outputs:
+        if output.endswith(".tex"):
+            to_latex(output)
+    if not any(o.endswith(".pdf") for o in outputs):
+        return
+    # A PDF is built where Calkit keeps what it derives from the file, and
+    # dated by the file's last commit rather than the build directory's,
+    # which has none of its own
+    build_dir = Path(".calkit", "markdown", md_path, "pdf").as_posix()
+    tex_path = f"{build_dir}/{Path(md_path).stem}.tex"
+    to_latex(tex_path)
+    cmd = [sys.executable, "-m", "calkit", "latex", "build"]
+    if environment is not None:
+        cmd += ["-e", environment]
+    if no_check:
+        cmd += ["--no-check"]
+    env = os.environ.copy()
+    epoch = calkit.latex.get_source_date_epoch(md_path)
+    if epoch is not None:
+        env["SOURCE_DATE_EPOCH"] = epoch
+    try:
+        subprocess.check_call(cmd + [tex_path], env=env)
+    except subprocess.CalledProcessError:
+        raise_error(f"LaTeX failed to build {tex_path}")
+    for output in outputs:
+        if output.endswith(".pdf"):
+            if os.path.dirname(output):
+                os.makedirs(os.path.dirname(output), exist_ok=True)
+            shutil.copyfile(Path(tex_path).with_suffix(".pdf"), output)
+
+
 def _tex_cmd(
     tex_cmd: list[str],
     environment: str | None,
@@ -2773,6 +2954,12 @@ def merge_docx(
                     and existing.resolved == tc.resolved
                 ):
                     continue
+                # Word can't carry these, so they come from the source
+                tc.id, tc.issue, tc.attrs = (
+                    existing.id,
+                    existing.issue,
+                    existing.attrs,
+                )
                 # Word knows neither emails nor what the source already
                 # recorded, so carry those over for unchanged messages
                 known = {(e.author, e.text): e for e in existing.entries}
@@ -2850,3 +3037,270 @@ def merge_docx(
         f"already there, {counts['pending']} pending, {counts['unplaced']} "
         f"unplaced); {added} comments added, {updated} updated"
     )
+
+
+comments_app = typer.Typer(no_args_is_help=True)
+latex_app.add_typer(
+    comments_app,
+    name="comments",
+    help="Work with review comments in LaTeX source.",
+)
+
+_ID_OPTION = typer.Option("--id", help="ID of the thread.")
+_LINE_OPTION = typer.Option(
+    "--line", "-l", help="Number of any line in the thread."
+)
+
+
+def _new_entry(
+    text: str, author: str | None, email: str | None
+) -> calkit.latex.Entry:
+    import datetime
+
+    import git
+
+    if author is None:
+        try:
+            author = git.Git().config("--get", "user.name").strip()
+            email = email or git.Git().config("--get", "user.email").strip()
+        except git.GitCommandError:
+            raise_error("Set --author, or Git's user.name")
+    date = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
+    return calkit.latex.Entry(author, text, email or None, date)
+
+
+def _edit_comment(
+    tex_path: str,
+    id: str | None,
+    line: int | None,
+    edit: Callable[[calkit.latex.TexComment], None],
+) -> calkit.latex.TexComment:
+    """Apply an edit to one thread and write the file back, giving the
+    thread an ID if it had none."""
+    if (id is None) == (line is None):
+        raise_error("Specify one of --id or --line")
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    lines = Path(tex_path).read_text(encoding="utf-8").split("\n")
+    tc = calkit.latex.find_comment(lines, id=id, lineno=line)
+    if tc is None:
+        raise_error(f"No comment thread in {tex_path} at {id or line}")
+    edit(tc)
+    tc.id = tc.id or calkit.latex.new_comment_id()
+    calkit.latex.write_comment(lines, tc)
+    Path(tex_path).write_text("\n".join(lines), encoding="utf-8")
+    return tc
+
+
+@comments_app.command(name="list")
+def list_comments(
+    tex_path: Annotated[
+        str,
+        typer.Argument(
+            help="Document to list comments from, including files it inputs."
+        ),
+    ],
+    unresolved: Annotated[
+        bool,
+        typer.Option("--unresolved", "-u", help="Only list open threads."),
+    ] = False,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """List the comment threads in a LaTeX document."""
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    out = [
+        c
+        for c in calkit.latex.list_comments(tex_path)
+        if not (unresolved and c["resolved"])
+    ]
+    if as_json:
+        typer.echo(json.dumps(out, indent=2))
+        return
+    for c in out:
+        status = " (resolved)" if c["resolved"] else ""
+        typer.echo(f"{c['path']}:{c['line']} [{c['id'] or '-'}]{status}")
+        if c["highlight"]:
+            typer.echo(f'  On "{c["highlight"]["text"]}"')
+        for m in c["messages"]:
+            typer.echo(f"  {m['author']}: {m['text']}")
+
+
+@comments_app.command(name="locate")
+def locate_paragraph(
+    tex_path: Annotated[
+        str,
+        typer.Argument(help="Document to search, including files it inputs."),
+    ],
+    text: Annotated[
+        str | None,
+        typer.Option(
+            "--text", help="Rendered text, e.g., a line copied from the PDF."
+        ),
+    ] = None,
+    path: Annotated[
+        str | None,
+        typer.Option("--path", help="File with the line to look up."),
+    ] = None,
+    line: Annotated[
+        int | None,
+        typer.Option("--line", "-l", help="Line to look up in --path."),
+    ] = None,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Find the paragraph some rendered text is in, or a source line is in.
+
+    This is how a place in a PDF built without SyncTeX, or by someone else,
+    can be matched to the source.
+    """
+    if (text is None) == (line is None):
+        raise_error("Specify one of --text or --path and --line")
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    found = calkit.latex.locate_block(tex_path, text, path, line)
+    if found is None:
+        raise_error("No matching paragraph found")
+    out = {
+        "path": found.path,
+        "line": found.lineno,
+        "end_line": found.lines[-1].lineno,
+        "text": found.text or calkit.latex.display_text(found),
+    }
+    if as_json:
+        typer.echo(json.dumps(out, indent=2))
+    else:
+        typer.echo(f"{out['path']}:{out['line']}")
+
+
+@comments_app.command(name="add")
+def add_comment(
+    tex_path: Annotated[str, typer.Argument(help="File to comment in.")],
+    line: Annotated[
+        int,
+        typer.Option(
+            "--line",
+            "-l",
+            help="A line in, or just above, the paragraph to comment on.",
+        ),
+    ],
+    text: Annotated[str, typer.Option("--text", "-m", help="The comment.")],
+    highlight: Annotated[
+        str | None,
+        typer.Option(
+            "--highlight", help="Rendered text in the paragraph it's about."
+        ),
+    ] = None,
+    occ: Annotated[
+        int,
+        typer.Option(
+            "--occ", help="Which occurrence of the highlight text, from 0."
+        ),
+    ] = 0,
+    author: Annotated[
+        str | None,
+        typer.Option("--author", help="Defaults to Git's user.name."),
+    ] = None,
+    email: Annotated[
+        str | None,
+        typer.Option("--email", help="Defaults to Git's user.email."),
+    ] = None,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Output the thread as JSON.")
+    ] = False,
+) -> None:
+    """Start a comment thread above a paragraph, printing its ID."""
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    lines = Path(tex_path).read_text(encoding="utf-8").split("\n")
+    tc = calkit.latex.TexComment(
+        [_new_entry(text, author, email)],
+        highlight=highlight or None,
+        highlight_occ=occ,
+        id=calkit.latex.new_comment_id(),
+    )
+    try:
+        calkit.latex.add_comment(lines, line, tc)
+    except ValueError as e:
+        raise_error(str(e))
+    Path(tex_path).write_text("\n".join(lines), encoding="utf-8")
+    if as_json:
+        blks = calkit.latex.file_blocks(tex_path, lines)
+        typer.echo(
+            json.dumps(
+                calkit.latex.comment_to_dict(tex_path, tc, blks), indent=2
+            )
+        )
+    else:
+        typer.echo(tc.id)
+
+
+@comments_app.command(name="reply")
+def reply_to_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    text: Annotated[str, typer.Option("--text", "-m", help="The reply.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+    author: Annotated[
+        str | None,
+        typer.Option("--author", help="Defaults to Git's user.name."),
+    ] = None,
+    email: Annotated[
+        str | None,
+        typer.Option("--email", help="Defaults to Git's user.email."),
+    ] = None,
+) -> None:
+    """Reply to a comment thread."""
+    entry = _new_entry(text, author, email)
+    tc = _edit_comment(tex_path, id, line, lambda tc: tc.entries.append(entry))
+    typer.echo(tc.id)
+
+
+@comments_app.command(name="resolve")
+def resolve_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+) -> None:
+    """Mark a comment thread resolved."""
+
+    def edit(tc: calkit.latex.TexComment) -> None:
+        tc.resolved = True
+
+    typer.echo(_edit_comment(tex_path, id, line, edit).id)
+
+
+@comments_app.command(name="reopen")
+def reopen_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+) -> None:
+    """Mark a resolved comment thread open again."""
+
+    def edit(tc: calkit.latex.TexComment) -> None:
+        tc.resolved = False
+
+    typer.echo(_edit_comment(tex_path, id, line, edit).id)
+
+
+@comments_app.command(name="delete")
+def delete_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+) -> None:
+    """Delete a comment thread and its replies."""
+    if (id is None) == (line is None):
+        raise_error("Specify one of --id or --line")
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    lines = Path(tex_path).read_text(encoding="utf-8").split("\n")
+    tc = calkit.latex.find_comment(lines, id=id, lineno=line)
+    if tc is None:
+        raise_error(f"No comment thread in {tex_path} at {id or line}")
+    del lines[tc.lineno - 1 : tc.lineno - 1 + tc.nlines]
+    Path(tex_path).write_text("\n".join(lines), encoding="utf-8")

calkit/git.py

@@ -131,7 +131,8 @@ def get_staged_files(
         repo = get_repo(path)
     cmd = ["--staged", "--name-only"]
     if path is not None:
-        cmd.append(path)
+        # A staged deletion's path is gone, so Git would read it as a ref
+        cmd += ["--", path]
     diff = repo.git.diff(cmd)
     paths = diff.split("\n")
     return [p for p in paths if p]
@@ -166,7 +167,8 @@ def get_staged_files_with_status(
         repo = get_repo(path)
     cmd = ["--staged", "--name-status"]
     if path is not None:
-        cmd.append(path)
+        # A staged deletion's path is gone, so Git would read it as a ref
+        cmd += ["--", path]
     diff = repo.git.diff(cmd)
     paths = diff.split("\n")
     res = []