Raven-1/tests/test_ppt_engine_script_edit.py
Tchen 5b4cce3f43 feat(ppt-engine): deliver where the user named, one route onto a page, and the ten templates
## Summary

This branch folds four merge requests and one unpushed commit into one, so that `main`
takes one review, one approval and one merge instead of four, and so the eight-file
overlap between them is resolved once. It carries, in this order:

- **!602** `feat/ppt_deliver_to_named_path` -- `ppt_build` takes `deliver_to`; every
  publish writes the deck under `out/` and copies the same measured bytes to the path
  the user named, recording it with `role: "delivery"`. The PDF preview rides along only
  where its own `.pdf` name is free: a file already at that stem is the user's and is
  left alone, and the reply says the preview stayed under `out/`.
- **!628** `feat/ppt_copy_route_and_page_isolation` -- `adapt` is removed, so cloning a
  template page and writing into it with `replace_text` is the only route; a page whose
  block raises loses only itself and the pages after it still build; a draft counts
  against the tier's build cap and one is released at it.
- **!632** `feat/ship_templates_and_soffice_dep` -- the ten bundled deck templates are
  tracked in git with per-file sha256 pins, so a fresh clone can build a deck; the
  LibreOffice dependency is declared and resolved through one resolver.
- **!642** `fix/ppt_copy_route_and_clone_typography` -- a copy-route lookup that finds
  nothing names the near miss before the inventory; a text frame with no paragraph at
  all can be written into; a cloned page's title size is said; `row_type_drift` compares
  the same structural slot across a run's units.
- **D57's other-page clause, rewired.** D57 gave five refusals a "did you mean" hint,
  and one of them also answered "the string you named is on page N of this template".
  That clause needs the file a page was cloned out of, and the only refusal holding it
  was `adapt`'s, which !628 removed. It is restored by reading `PPT_TEMPLATE_SOURCE`,
  which the runner already sets in the author's own process and which this module
  already reads for `bundled()`; the two helpers behind the clause are unchanged.
- **D60** `read the ground under each word, not across the whole box` -- the `unreadable`
  contrast gate also measures the render's own word boxes, as extra regions through the
  same guards, so a two-line block crossed by a narrow bright ridge can no longer elect
  the dark ground and read as legible.

Decisions the union forced, none of which drops a behaviour:

- The publish record is built !602's way, with its delivery `role`, and written the way
  D49 requires -- read back off the file, atomic, and refused rather than silent when
  the record cannot be written.
- `clear_region`, `shapes_in`, `page_box` and the refusal of a bare four-number region
  survive `adapt`'s removal; so do `_heading_rows` and its helpers, which the row
  reading loads even though the call they were written for is gone.
- The author-facing guidance names !628's single route and keeps D59's rule that a
  region must declare which reading it is.
**The decision log carries a numbering collision, on purpose.** It is a set union with
no wording changed, and the numbers are left exactly as each branch wrote them, so a
reviewer meets this rather than discovers it:

- !602 and !628 each wrote a **D37** and a **D38**, about different decisions.
- !628's **D45** is not `main`'s D45; they are unrelated entries under one number.
- !628's **D42** is `main`'s **D45** word for word, so the merged log carries one
  decision under two numbers.

Renumbering touches every cross-reference in the log, and doing that inside a
seventy-commit fold immediately before a merge is how a silent break gets in. The
numbering is being fixed on a separate branch, which carries a script and a test that
fails when a citation points at nothing.

## Type

- [x] Feature
- [x] Fix
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run on an interpreter carrying `python-pptx`, with `PYTHONPATH` at this worktree and its
`plugins-dist/ppt-engine`, confirmed from a neutral working directory that `raven` and
`raven_ppt` resolve out of the worktree and not the host repo.

- `make test-python` (the whole suite, as CI runs it) -- 20826 passed, 49 skipped, and
  26 failures this machine produces on any branch: it has no `/usr/share/zoneinfo`, so
  every cron timezone case raises `ValueError: unknown timezone 'Asia/Shanghai'`. Checked
  out plain `origin/main` in a clean worktree and ran the same two files: the same 6
  failed and 20 errors, the ids identical character for character. Nothing on this branch
  touches cron or timezones. The stale `test_trunks_executor_would_have_dropped_that_output`
  that failed on the previous revision is retired on the new base and its replacement,
  `test_trunks_executor_preserves_output_on_timeout`, was run on its own and passes.
  The 6 failures and 20 errors are all cron timezone tests failing identically on plain
  `main` in a clean worktree, on a host with no `/usr/share/zoneinfo`.
- `make check-commits` -- exit 0.
- `make check-source-language` -- exit 0.
- `make check-large-files` -- exit 0.
- `make lint-imports` -- exit 0, 9 contracts kept, 0 broken.
- `ruff check` and `ruff format --check` over the 80 changed Python files -- exit 0.
- `pytest tests/test_ppt_engine_templates.py tests/test_utils_office.py
  tests/test_cli_doctor_commands.py` -- 97 passed; the ten templates are tracked and
  satisfy their pins, and the soffice resolver finds the local binary.
- The delivery contract, the record read-back, the page isolation and the near miss were
  each run as a measurement rather than asserted; the `unreadable` gate was run through
  the real LibreOffice render chain on a delivered 12-page deck and reports BLOCKING on
  page 12 under one word at 1.6:1.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

User-visible changes: `ppt_build` gains `deliver_to` and delivers outside `out/`;
`adapt` is gone from the author-facing template module, so a program calling it fails to
import -- `title=` and `subtitle=` have no replacement and the heading is named by the
words the template put there; a draft now counts against the tier's build cap; three
gates that nothing measured against being wrong no longer refuse; and the ten templates
are now bytes in the repository rather than a private registry fetch.

Two pieces here are about not destroying something the user has. The delivery
refuses to write its `.pdf` where a file the user already owns sits at the same
stem, rather than replacing it; and the large-file roster moved out of the manifest
inside the tree being checked and into the gate's own source, so a change can no
longer grant itself the exception the gate exists to withhold.

Rollback is per piece: each of the five sources is a contiguous run of commits on this
branch, in the order listed above, so any one of them can be reverted as a range without
touching the others.

- [x] Backward compatibility considered
- [x] Security impact considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-11 05:52:36 +00:00

130 lines
4.6 KiB
Python

"""Rewriting one page without breaking the other seventeen.
Every case here is a round that was lost. The prelude checks come from an edit
that took the deck from finished to unbuildable; the whole-write verification
comes from a round that built eighteen slides from seventeen mapped blocks.
"""
from __future__ import annotations
import textwrap
from raven_ppt.backends.script import blocks_rejection, page_blocks
PRELUDE = textwrap.dedent(
"""
import os
from pptx import Presentation
from pptx.util import Inches
from ppt_theme import THEMES, rgb
TH = THEMES["ink-graphite"]
ACC = rgb(TH["accent"])
MUT = rgb(TH["muted"])
FNT = "Source Serif 4"
prs = Presentation()
def new_slide():
return prs.slides.add_slide(prs.slide_layouts[6])
def title(slide, text):
slide.shapes.add_textbox(Inches(0.8), Inches(0.6), Inches(11), Inches(1)).text_frame.text = text
def footnote(slide, text):
slide.shapes.add_textbox(Inches(0.8), Inches(6.8), Inches(11), Inches(0.4)).text_frame.text = text
"""
).lstrip()
SCRIPT = PRELUDE + textwrap.dedent(
"""
# SLIDE 1
one = new_slide()
title(one, "Unified video segmentation")
# SLIDE 2
two = new_slide()
title(two, "Target queries")
prs.save(os.environ["PPT_OUTPUT"])
"""
)
BLOCKS_TEXT = "one = new_slide()\ntitle(one, 'x')\ntwo = new_slide()\ntitle(two, 'y')\n"
def test_a_page_cloned_from_the_template_counts_as_a_page() -> None:
"""`clone_page` creates a slide -- through `add_slide`, inside -- and the text scan
could not see that. With the structural pages cloned, the block that draws slide 1
holds a `clone_page` call and no `add_slide`, so the whole design pass refused:
measured across two live runs, every finished build, which is the pass the deck was
counting on for its layout."""
lines = (
PRELUDE + "\n# SLIDE 1\nslide = clone_page(prs, prototype(tpl, 1))\n" + "\n# SLIDE 2\nslide = new_slide()\n"
).splitlines(keepends=True)
blocks = page_blocks(lines)
assert blocks_rejection(lines, blocks, slide_count=2) is None
def test_the_ordinary_way_to_make_a_page_is_a_method_call() -> None:
"""`prs.slides.add_slide(LAY)` is how every drawn page starts, dots and all.
The first fix for the cloned-page case excluded a leading dot -- to keep
`ppt_template.prototype(tpl, 1)` from counting as a creator -- and that turned every
drawn page into a block that draws nothing. Both real scripts measured refused on
their first drawn page.
"""
lines = (
PRELUDE
+ "\n# SLIDE 1\nslide = prs.slides.add_slide(LAY)\ntitle(slide, 'drawn')\n"
+ "\n# SLIDE 2\nslide = clone_page(prs, prototype(tpl, 2))\n"
).splitlines(keepends=True)
blocks = page_blocks(lines)
assert blocks_rejection(lines, blocks, slide_count=2) is None
def test_a_block_count_that_disagrees_with_the_deck_is_refused() -> None:
lines = SCRIPT.splitlines(keepends=True)
blocks = page_blocks(lines)
reason = blocks_rejection(lines, blocks, slide_count=3)
assert reason is not None and "2 page block(s)" in reason and "3 slide(s)" in reason
def test_the_advice_differs_by_where_the_mapping_came_from() -> None:
"""Execution is already exact, so a mismatch means the script has no per-page block."""
lines = SCRIPT.splitlines(keepends=True)
blocks = page_blocks(lines)
from_comments = blocks_rejection(lines, blocks, 3, derived="comments")
from_execution = blocks_rejection(lines, blocks, 3, derived="execution")
assert "# SLIDE <n>" in (from_comments or "")
assert "shared loop" in (from_execution or "")
def test_execution_mapping_accepts_a_page_created_through_nested_helpers() -> None:
script = PRELUDE + "\n# SLIDE 1\nslide, body = content_page('title')\n"
lines = script.splitlines(keepends=True)
blocks = page_blocks(lines)
assert "creates 0 slides" in (blocks_rejection(lines, blocks, 1, derived="comments") or "")
assert blocks_rejection(lines, blocks, 1, derived="execution") is None
def test_pages_numbered_out_of_range_are_refused() -> None:
script = SCRIPT.replace("# SLIDE 2", "# SLIDE 5")
lines = script.splitlines(keepends=True)
reason = blocks_rejection(lines, page_blocks(lines), slide_count=2)
assert reason is not None and "not 1..2" in reason
def test_a_block_that_draws_two_slides_is_refused() -> None:
script = SCRIPT.replace('title(two, "Target queries")', 'three = new_slide()\ntitle(three, "x")')
lines = script.splitlines(keepends=True)
reason = blocks_rejection(lines, page_blocks(lines), slide_count=2)
assert reason is not None and "creates 2 slides" in reason