quartobot 0.1.0__py3-none-any.whl

quartobot/__init__.py

@@ -0,0 +1,6 @@
+"""quartobot: the manubot manuscript-as-software pattern, on Quarto."""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"
+__all__ = ["__version__"]

quartobot/cli.py

@@ -0,0 +1,215 @@
+"""Command-line interface for quartobot."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from quartobot import __version__
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, prog_name="quartobot")
+def main() -> None:
+    """quartobot: manuscript-as-software, on Quarto.
+
+    Pre-render and out-of-render tooling for Quarto projects that use the
+    quarto-manubot-cite extension.
+    """
+
+
+@main.command()
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path),
+    default=".",
+)
+def scan(path: Path) -> None:
+    """Scan a Quarto project for cite keys and group by prefix.
+
+    Walks .qmd and .md files under PATH, extracts cite keys (both
+    persistent-identifier ones like @doi: and @pmid:, and hand-curated
+    keys), and reports counts and duplicates. Pure read; no network.
+
+    Exits 1 if any duplicates are found (so it works as a pre-commit
+    hook), 0 otherwise.
+    """
+    from quartobot.scan import format_scan_result, scan_path
+
+    result = scan_path(path)
+    relative_to = path if path.is_dir() else path.parent
+    click.echo(format_scan_result(result, relative_to=relative_to))
+    if result.duplicates:
+        raise SystemExit(1)
+
+
+@main.command()
+@click.argument("keys", nargs=-1)
+@click.option(
+    "--from-scan",
+    type=click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path),
+    default=None,
+    help="Resolve every persistent-identifier key found by scanning this path.",
+)
+@click.option(
+    "--output",
+    type=click.Path(file_okay=True, dir_okay=False, path_type=Path),
+    default="references.json",
+    show_default=True,
+    help="Path to write the resolved CSL JSON bibliography to.",
+)
+@click.option(
+    "--cache",
+    type=click.Path(file_okay=True, dir_okay=False, path_type=Path),
+    default=None,
+    help=(
+        "Optional path to read cached entries from. Cache hits skip the "
+        "network call. Defaults to the value of --output, so resolve is "
+        "idempotent against its own previous output."
+    ),
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Report what would be resolved without making network calls.",
+)
+@click.option(
+    "--id-mode",
+    type=click.Choice(["short-hash", "citation-key"]),
+    default="short-hash",
+    show_default=True,
+    help=(
+        "How to populate the CSL `id` field. `short-hash` (default) "
+        "keeps manubot's hash form, which the `pandoc-manubot-cite` "
+        "filter expects. `citation-key` writes the original "
+        "`prefix:identifier`, which lets pandoc-citeproc match prose "
+        "keys directly with no filter in the chain — the pre-render-"
+        "hook architecture."
+    ),
+)
+def resolve(
+    keys: tuple[str, ...],
+    from_scan: Path | None,
+    output: Path,
+    cache: Path | None,
+    dry_run: bool,
+    id_mode: str,
+) -> None:
+    """Pre-fetch citations and write CSL JSON to disk.
+
+    Resolves persistent-identifier cite keys via manubot.cite and writes
+    the resulting CSL JSON to --output (default `references.json`). The
+    point isn't to replace what manubot does at render — it's to do the
+    network work on a developer's machine ahead of push, so CI never
+    sees a Crossref or PubMed hiccup.
+
+    Pass keys as arguments (`@doi:10.x/y pmid:12345`) or use --from-scan
+    to resolve every persistent-identifier cite found in a project.
+    Hand-curated keys (no recognized prefix) are skipped — those live
+    in references.bib and pandoc citeproc handles them.
+
+    Exits 1 if any keys fail to resolve, 0 otherwise.
+    """
+    from quartobot.resolve import collect_resolvable_keys, format_outcome, resolve_keys
+
+    collected: list[str] = []
+    for k in keys:
+        # Allow either `@doi:10.x/y` or `doi:10.x/y` — strip leading @.
+        collected.append(k.lstrip("@"))
+
+    if from_scan is not None:
+        collected.extend(collect_resolvable_keys(from_scan))
+
+    # De-dup while preserving order.
+    seen: set[str] = set()
+    unique: list[str] = []
+    for k in collected:
+        if k not in seen:
+            seen.add(k)
+            unique.append(k)
+
+    if not unique:
+        click.echo("No persistent-identifier cite keys to resolve.")
+        return
+
+    cache_path = cache if cache is not None else output
+    outcome = resolve_keys(
+        unique,
+        cache_path=cache_path,
+        output_path=output,
+        dry_run=dry_run,
+        id_mode=id_mode,
+    )
+    click.echo(format_outcome(outcome))
+    if outcome.failures:
+        raise SystemExit(1)
+
+
+@main.command()
+@click.argument(
+    "project",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    default=".",
+)
+def validate(project: Path) -> None:
+    """Pre-flight check a Quarto project for the quartobot pattern.
+
+    Runs a battery of static config checks: the extension is installed,
+    `_quarto.yml` declares `bibliography:` and the manubot keys, the
+    output bibliography is also in the bibliography list, no duplicate
+    cite keys across files.
+
+    Citation-resolution checks (does Crossref actually return metadata
+    for this DOI?) are out of scope here — they need network. Run
+    `quartobot resolve --dry-run --from-scan .` if you want that.
+
+    Exits 1 if any check fails, 0 if all pass.
+    """
+    from quartobot.validate import format_outcome, validate_project
+
+    outcome = validate_project(project)
+    click.echo(format_outcome(outcome))
+    if not outcome.passed:
+        raise SystemExit(1)
+
+
+@main.command()
+@click.argument(
+    "project",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    default=".",
+)
+@click.option(
+    "--project-type",
+    type=click.Choice(["auto", "manuscript", "book"]),
+    default="auto",
+    show_default=True,
+    help=(
+        "Quarto project shape. `auto` detects from an existing _quarto.yml "
+        "and falls back to manuscript when there's nothing to detect from."
+    ),
+)
+def init(project: Path, project_type: str) -> None:
+    """Scaffold the quartobot pattern into an existing Quarto project.
+
+    Writes the files that make a vanilla Quarto project adopt the
+    quartobot pattern: `_quarto.yml` (when absent), `references.bib`,
+    the version banner template + dev placeholder, a ten-line GitHub
+    Actions workflow that calls the upstream reusable workflow, the
+    PR-cleanup workflow, and `.gitignore` augments.
+
+    Conservative — never overwrites existing files. If `_quarto.yml`
+    already exists, prints a YAML snippet to merge in manually.
+
+    Doesn't run `quarto add` or `pip install` for you; the printed
+    "next steps" walk through both.
+    """
+    from quartobot.init_project import format_outcome, init_project
+
+    outcome = init_project(project, project_type=project_type)
+    click.echo(format_outcome(outcome, project=project))
+
+
+if __name__ == "__main__":
+    main()

quartobot/init_project.py

@@ -0,0 +1,428 @@
+"""Scaffold the quartobot pattern into an existing Quarto project.
+
+`quartobot init` writes the files that make a vanilla Quarto project
+adopt the quartobot pattern: a manubot-wired `_quarto.yml`, a seed
+`references.bib`, the version-banner HTML template, a `.gitignore`
+augment, and a ten-line GitHub Actions workflow that calls the upstream
+reusable workflow.
+
+Conservative by default:
+
+- Files that already exist are NEVER overwritten. `init` skips them and
+  reports what it skipped.
+- `_quarto.yml` is the one file where partial overlap is likely — for
+  that path, if the file exists, init prints a YAML snippet the user
+  should merge in manually.
+- `.gitignore` gets new lines appended (idempotent).
+- The Quarto extension itself is installed by `quarto add` (run
+  separately); init only scaffolds the surrounding files.
+
+The flow is intentionally pre-`usethis`: no interactive prompts, no
+auto-merge. Once the CLI matures we can add `--force` for overwrites
+and a `quartobot use-<thing>` family for piecewise scaffolding.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+# ---------------------------------------------------------------- templates
+
+
+_QUARTO_YML_MANUSCRIPT = """\
+project:
+  type: default
+
+filters:
+  - quarto-manubot-cite
+
+# Manubot wiring. Defaults shipped by the quartobot extension; tune as needed.
+manubot-output-bibliography: references.json
+manubot-bibliography-cache: _freeze/manubot-cache.json
+manubot-fail-on-errors: false
+manubot-infer-citekey-prefixes: true
+
+bibliography:
+  - references.bib
+  - references.json
+
+format:
+  html:
+    toc: true
+    embed-resources: true
+    include-before-body:
+      - _version-banner.html
+  pdf:
+    documentclass: article
+    keep-tex: true
+"""
+
+_QUARTO_YML_BOOK = """\
+project:
+  type: book
+
+book:
+  title: "My quartobot book"
+  author: "Your Name"
+  date: today
+  chapters:
+    - index.qmd
+  search: true
+  page-navigation: true
+
+filters:
+  - quarto-manubot-cite
+
+manubot-output-bibliography: references.json
+manubot-bibliography-cache: _freeze/manubot-cache.json
+manubot-fail-on-errors: false
+manubot-infer-citekey-prefixes: true
+
+bibliography:
+  - references.bib
+  - references.json
+
+format:
+  html:
+    theme: cosmo
+    toc: true
+    include-before-body:
+      - _version-banner.html
+"""
+
+_REFERENCES_BIB = """\
+% Hand-curated entries live here. Auto-resolved entries written by
+% pandoc-manubot-cite land in references.json (regenerated each
+% render, ignored by git).
+"""
+
+# Embedded HTML banners. Lines are long because CSS is inlined for
+# users who want to drop the file into a fresh project without
+# wrangling a separate stylesheet. Lint exceptions tagged per-line.
+# fmt: off
+_VERSION_BANNER_TEMPLATE = (
+    '<div class="version-banner" style="background:#fff7e0;border-bottom:2px solid #f0b400;padding:0.55rem 1rem;font-family:system-ui,-apple-system,\'Segoe UI\',sans-serif;font-size:0.92rem;text-align:center;color:#3a2c00;">\n'  # noqa: E501
+    "  <strong>This version:</strong>\n"
+    '  <a href="__VERSION_URL__" style="color:#3a2c00;text-decoration:underline;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;">__VERSION_SHA__</a>\n'  # noqa: E501
+    "  &nbsp;&middot;&nbsp;\n"
+    '  <a href="__VERSION_LATEST__" style="color:#3a2c00;">latest&nbsp;HTML</a>\n'
+    "  &nbsp;&middot;&nbsp;\n"
+    '  <a href="__VERSION_GH__" style="color:#3a2c00;">GitHub</a>\n'
+    "</div>\n"
+)
+
+_VERSION_BANNER_DEV = (
+    '<div class="version-banner" style="background:#eef2ff;border-bottom:2px solid #6366f1;padding:0.55rem 1rem;font-family:system-ui,-apple-system,\'Segoe UI\',sans-serif;font-size:0.92rem;text-align:center;color:#1e1b4b;">\n'  # noqa: E501
+    "  <strong>Development build</strong> &middot; permalink set by CI on push to <code>main</code>\n"  # noqa: E501
+    "</div>\n"
+)
+# fmt: on
+
+
+def _render_workflow(project_type: str) -> str:
+    """Return the ten-line workflow caller for the given project type."""
+    return f"""\
+# Renders on every push and PR via the upstream reusable workflow.
+# Override inputs in the `with:` block below; see
+#   https://github.com/seandavi/quartobot/blob/main/.github/workflows/render-reusable.yml
+# for the full list.
+
+name: Render
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  render:
+    uses: seandavi/quartobot/.github/workflows/render-reusable.yml@main
+    permissions:
+      contents: write
+      pull-requests: write
+    with:
+      project-type: {project_type}
+"""
+
+
+_PR_CLOSED_WORKFLOW = """\
+name: Clean up PR preview
+
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - name: Check whether gh-pages branch exists
+        id: branch
+        run: |
+          if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check out gh-pages
+        if: steps.branch.outputs.exists == 'true'
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          fetch-depth: 1
+
+      - name: Remove PR preview directory
+        if: steps.branch.outputs.exists == 'true'
+        run: |
+          pr="${{ github.event.pull_request.number }}"
+          [ -d "pr/${pr}" ] && rm -rf "pr/${pr}" || exit 0
+
+      - name: Commit and push
+        if: steps.branch.outputs.exists == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if git diff --cached --quiet; then exit 0; fi
+          git commit -m "Clean up preview for PR #${{ github.event.pull_request.number }}"
+          git push
+"""
+
+
+_GITIGNORE_LINES = [
+    "# quartobot",
+    "_book/",
+    "_freeze/",
+    ".quarto/",
+    "_extensions/",
+    "references.json",
+    "*_files/",
+    "**/*.quarto_ipynb",
+]
+
+
+# ---------------------------------------------------------------- outcome types
+
+
+ActionStatus = Literal["written", "skipped-exists", "appended", "manual-merge"]
+
+
+@dataclass(frozen=True)
+class Action:
+    """One file write (or non-write) the init flow attempted."""
+
+    path: Path
+    status: ActionStatus
+    detail: str | None = None
+
+
+@dataclass
+class InitOutcome:
+    """The aggregate result of an init run."""
+
+    actions: list[Action] = field(default_factory=list)
+    project_type: str = "manuscript"
+    manual_merge_snippet: str | None = None
+
+
+# ---------------------------------------------------------------- helpers
+
+
+def detect_project_type(project: Path) -> str:
+    """Read `_quarto.yml`; return `"manuscript"`, `"book"`, or `"unknown"`.
+
+    A missing or unparsable `_quarto.yml` returns `"unknown"` — init
+    treats that as the manuscript default.
+    """
+    yml = project / "_quarto.yml"
+    if not yml.exists():
+        return "unknown"
+    try:
+        loaded = yaml.safe_load(yml.read_text(encoding="utf-8"))
+    except yaml.YAMLError:
+        return "unknown"
+    if not isinstance(loaded, dict):
+        return "unknown"
+    proj = loaded.get("project")
+    if isinstance(proj, dict) and proj.get("type") == "book":
+        return "book"
+    return "manuscript"
+
+
+def _write_if_missing(path: Path, content: str) -> Action:
+    if path.exists():
+        return Action(path=path, status="skipped-exists")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return Action(path=path, status="written")
+
+
+def _ensure_gitignore(project: Path) -> Action:
+    """Append missing lines to `.gitignore`. Idempotent."""
+    gi = project / ".gitignore"
+    existing = gi.read_text(encoding="utf-8").splitlines() if gi.exists() else []
+    existing_set = set(existing)
+    to_add = [line for line in _GITIGNORE_LINES if line not in existing_set]
+    if not to_add:
+        return Action(path=gi, status="skipped-exists", detail="all lines present")
+    if existing and existing[-1] != "":
+        existing.append("")  # leading blank separator
+    new_lines = existing + to_add + [""]
+    gi.write_text("\n".join(new_lines), encoding="utf-8")
+    return Action(
+        path=gi,
+        status="appended",
+        detail=f"added {len(to_add)} line(s)",
+    )
+
+
+# ---------------------------------------------------------------- top-level
+
+
+def init_project(
+    project: Path,
+    *,
+    project_type: str = "auto",
+) -> InitOutcome:
+    """Scaffold quartobot files into `project`.
+
+    Args:
+        project: Path to an existing Quarto project root (or empty dir).
+        project_type: `"auto"` (detect from existing `_quarto.yml`),
+            `"manuscript"`, or `"book"`. `"auto"` defaults to
+            `"manuscript"` when there's nothing to detect from.
+
+    Returns:
+        `InitOutcome` describing each file action.
+    """
+    if project_type == "auto":
+        detected = detect_project_type(project)
+        ptype = detected if detected != "unknown" else "manuscript"
+    else:
+        ptype = project_type
+
+    outcome = InitOutcome(project_type=ptype)
+
+    # _quarto.yml — never overwrite. If absent, write the appropriate
+    # default. If present, print a snippet for manual merge.
+    yml_path = project / "_quarto.yml"
+    if yml_path.exists():
+        outcome.actions.append(
+            Action(
+                path=yml_path,
+                status="manual-merge",
+                detail="merge the manubot block manually",
+            )
+        )
+        outcome.manual_merge_snippet = _quarto_yml_snippet_for_manual_merge()
+    else:
+        content = _QUARTO_YML_BOOK if ptype == "book" else _QUARTO_YML_MANUSCRIPT
+        outcome.actions.append(_write_if_missing(yml_path, content))
+
+    # Other files — write only if missing.
+    outcome.actions.append(_write_if_missing(project / "references.bib", _REFERENCES_BIB))
+    outcome.actions.append(
+        _write_if_missing(
+            project / "_version-banner.html.template",
+            _VERSION_BANNER_TEMPLATE,
+        )
+    )
+    outcome.actions.append(_write_if_missing(project / "_version-banner.html", _VERSION_BANNER_DEV))
+    outcome.actions.append(
+        _write_if_missing(
+            project / ".github" / "workflows" / "render.yml",
+            _render_workflow(ptype),
+        )
+    )
+    outcome.actions.append(
+        _write_if_missing(
+            project / ".github" / "workflows" / "pr-closed.yml",
+            _PR_CLOSED_WORKFLOW,
+        )
+    )
+
+    # .gitignore is the only file where we modify-in-place.
+    outcome.actions.append(_ensure_gitignore(project))
+
+    return outcome
+
+
+def _quarto_yml_snippet_for_manual_merge() -> str:
+    """Return the YAML lines to add to an existing `_quarto.yml`."""
+    return """\
+# Add to your existing _quarto.yml:
+
+filters:
+  - quarto-manubot-cite
+
+manubot-output-bibliography: references.json
+manubot-bibliography-cache: _freeze/manubot-cache.json
+manubot-fail-on-errors: false
+manubot-infer-citekey-prefixes: true
+
+bibliography:
+  - references.bib
+  - references.json
+
+format:
+  html:
+    include-before-body:
+      - _version-banner.html
+"""
+
+
+def format_outcome(outcome: InitOutcome, *, project: Path) -> str:
+    """Pretty-print an InitOutcome."""
+    glyphs = {
+        "written": "+",
+        "appended": "~",
+        "skipped-exists": "·",
+        "manual-merge": "!",
+    }
+    lines: list[str] = []
+    lines.append(f"Project type: {outcome.project_type}")
+    lines.append("")
+    for action in outcome.actions:
+        try:
+            relative = action.path.relative_to(project)
+        except ValueError:
+            relative = action.path
+        glyph = glyphs.get(action.status, "?")
+        line = f"  {glyph} {relative}  [{action.status}]"
+        if action.detail:
+            line += f" — {action.detail}"
+        lines.append(line)
+    lines.append("")
+    if outcome.manual_merge_snippet:
+        lines.append(outcome.manual_merge_snippet)
+    lines.append("Next steps:")
+    lines.append("  1. quarto add seandavi/quartobot --no-prompt")
+    lines.append("  2. pip install 'manubot>=0.6,<0.7'")
+    lines.append("  3. Add citations to your prose: @doi:..., @pmid:..., etc.")
+    lines.append("  4. quarto render")
+    return "\n".join(lines)
+
+
+__all__: Sequence[str] = (
+    "Action",
+    "InitOutcome",
+    "detect_project_type",
+    "format_outcome",
+    "init_project",
+)