## 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
317 lines
15 KiB
Python
317 lines
15 KiB
Python
"""What gets registered, and the failure the predecessor could not see.
|
|
|
|
Its assembly function carried ten branches on one boolean, two of which
|
|
contradicted each other: a sub-route was registered under
|
|
`expert_outline and not free_composition` while `expert_outline` already implied
|
|
`free_composition`. Fifteen hundred lines of tooling were unreachable under every
|
|
configuration for months, and a test had frozen that as the expected behaviour.
|
|
|
|
The lesson is not "check that predicate". It is that assembly must verify its own
|
|
result against the route's declaration instead of trusting the arithmetic that
|
|
produced it.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
from raven_ppt.profiles import registry
|
|
from raven_ppt.tools.assembly import build_ppt_tools
|
|
|
|
pytest.importorskip("pptx")
|
|
|
|
|
|
def test_the_default_route_registers_its_tools(tmp_path: Path) -> None:
|
|
names = {tool.name for tool in build_ppt_tools(tmp_path)}
|
|
assert "ppt_build" in names
|
|
|
|
|
|
def test_every_registered_tool_is_one_the_route_asked_for(tmp_path: Path) -> None:
|
|
profile = registry.get(registry.DEFAULT)
|
|
names = {tool.name for tool in build_ppt_tools(tmp_path)}
|
|
assert names <= set(profile.tools), names - set(profile.tools)
|
|
|
|
|
|
def test_a_route_missing_a_tool_says_so_at_startup(tmp_path: Path, caplog) -> None:
|
|
"""Rather than at the point a model calls a tool nobody registered."""
|
|
with caplog.at_level(logging.WARNING):
|
|
build_ppt_tools(tmp_path)
|
|
missing = [r for r in caplog.records if "were not registered" in r.getMessage()]
|
|
if missing:
|
|
# The message must name what is absent; a warning that does not is noise.
|
|
assert "ppt_ingest" in missing[0].getMessage() or "ppt_figure_inspect" in missing[0].getMessage()
|
|
|
|
|
|
def test_an_unknown_route_falls_back_and_says_which(tmp_path: Path, caplog) -> None:
|
|
with caplog.at_level(logging.WARNING):
|
|
tools = build_ppt_tools(tmp_path, profile="no_such_route")
|
|
assert tools
|
|
assert any("falling back" in r.getMessage() for r in caplog.records)
|
|
|
|
|
|
def test_a_declared_route_with_no_backend_yet_registers_nothing(tmp_path: Path, caplog) -> None:
|
|
"""Saying so beats registering a route that fails at the first call."""
|
|
with caplog.at_level(logging.WARNING):
|
|
assert build_ppt_tools(tmp_path, profile="image_text") == []
|
|
assert any("not implemented yet" in r.getMessage() for r in caplog.records)
|
|
|
|
|
|
class _Provider:
|
|
async def chat_stream(self, *a, **k): # pragma: no cover - never called here
|
|
raise AssertionError
|
|
|
|
|
|
def test_the_gates_stand_with_or_without_a_second_model(tmp_path: Path) -> None:
|
|
"""A provider used to decide whether a whole stage existed. It buys per-page calls
|
|
inside `ppt_prepare` and `ppt_outline` now, and nothing about what a build measures:
|
|
the same measurer is wired either way."""
|
|
for tools in (build_ppt_tools(tmp_path), build_ppt_tools(tmp_path, provider=_Provider())):
|
|
tool = next(t for t in tools if t.name == "ppt_build")
|
|
assert tool.stage.measure is not None
|
|
|
|
|
|
# The vocabulary a model must never be handed: a type size, a font face, or a
|
|
# physical coordinate. Matched against the parts of a field name, so `font_size` and
|
|
# `slide_width` are caught the way `font` and `width` are.
|
|
PHYSICAL_QUANTITIES = (
|
|
"emu",
|
|
"inch",
|
|
"inches",
|
|
"px",
|
|
"pt",
|
|
"font",
|
|
"typeface",
|
|
"face",
|
|
"size",
|
|
"width",
|
|
"height",
|
|
"x0",
|
|
"y0",
|
|
"x1",
|
|
"y1",
|
|
"left",
|
|
"top",
|
|
)
|
|
|
|
# Normalised composition coordinates are the one documented exception (CLAUDE.md's
|
|
# hard invariant 1): a free-composition region is a 0..1000 grid and a vector canvas
|
|
# is 160x90, and neither is a physical quantity -- the engine maps them. Listed as
|
|
# whole field names rather than allowed by a rule, so the exception cannot widen on
|
|
# its own, and empty until a route actually declares one.
|
|
NORMALISED_FIELDS: frozenset[str] = frozenset()
|
|
|
|
|
|
def _named_fields(schema: object, path: str = "") -> list[str]:
|
|
"""Every field name anywhere in a JSON schema, with the route to it.
|
|
|
|
The check used to read `properties` at the top level only, which is the one place
|
|
a physical quantity was never going to appear: an outline's pages, a page's table
|
|
plan and a chart's series are all nested objects, and `ppt_outline` alone puts
|
|
three levels of them behind one top-level `pages`. Everything a schema can nest a
|
|
named field inside is followed -- `items`, the combinators, `$defs` and
|
|
`additionalProperties` when it is a schema rather than `False`.
|
|
"""
|
|
found: list[str] = []
|
|
if isinstance(schema, list):
|
|
for index, entry in enumerate(schema):
|
|
found.extend(_named_fields(entry, f"{path}[{index}]"))
|
|
return found
|
|
if not isinstance(schema, dict):
|
|
return found
|
|
for key, value in schema.items():
|
|
if key in ("properties", "$defs", "definitions", "patternProperties") and isinstance(value, dict):
|
|
for name, subschema in value.items():
|
|
found.append(f"{path}.{name}" if path else name)
|
|
found.extend(_named_fields(subschema, f"{path}.{name}" if path else name))
|
|
elif key in ("items", "prefixItems", "anyOf", "oneOf", "allOf", "not", "contains", "additionalProperties"):
|
|
found.extend(_named_fields(value, path))
|
|
return found
|
|
|
|
|
|
def test_the_schema_never_offers_a_physical_quantity(tmp_path: Path) -> None:
|
|
"""The hard invariant, checked at every depth a schema can hide a field at.
|
|
|
|
Two holes, and each made the check weaker than the sentence it was written for.
|
|
It compared the whole field name for equality against the banned list, so
|
|
`font_size`, `slide_width` and `body_font` all passed a test whose point is that
|
|
none of them may exist. And it read only the top-level `properties`, so every
|
|
field inside `ppt_outline`'s pages -- the part of the schema a model writes most
|
|
of -- was never looked at at all. Nothing violates it today, which is why the
|
|
weakness could sit there: a test that passes for the wrong reason looks exactly
|
|
like a test that passes.
|
|
"""
|
|
import re
|
|
|
|
offences = []
|
|
for tool in build_ppt_tools(tmp_path):
|
|
for field in _named_fields(tool.parameters):
|
|
name = field.rsplit(".", 1)[-1]
|
|
if name in NORMALISED_FIELDS:
|
|
continue
|
|
parts = {part.lower() for part in re.split(r"_|(?<=[a-z])(?=[A-Z])", name) if part}
|
|
caught = parts & set(PHYSICAL_QUANTITIES)
|
|
if caught:
|
|
offences.append(f"{tool.name}.{field} names {sorted(caught)}")
|
|
assert not offences, "the schema hands a model a physical quantity:\n " + "\n ".join(offences)
|
|
|
|
|
|
def test_the_scan_reaches_the_fields_the_flat_one_could_not_see(tmp_path: Path) -> None:
|
|
"""The guard on the guard: a recursive check that recursed into nothing would pass.
|
|
|
|
`ppt_outline` nests every page's fields under an array's `items`, so
|
|
`pages.claim` is only reachable by recursing through that array -- the shape the
|
|
old flat check was blind to, and the cheapest proof the new one is not. The
|
|
planted schema below carries the same nesting with a banned word at the bottom.
|
|
"""
|
|
tools = {tool.name: tool for tool in build_ppt_tools(tmp_path)}
|
|
outline = tools.get("ppt_outline")
|
|
if outline is None:
|
|
pytest.skip("the outline tool is not registered on the default route")
|
|
fields = _named_fields(outline.parameters)
|
|
assert "pages" in fields
|
|
assert "pages.claim" in fields, fields
|
|
assert "swept.url" in fields, fields
|
|
# And a field with a banned word in it has to be caught wherever it is nested.
|
|
planted = {
|
|
"type": "object",
|
|
"properties": {
|
|
"pages": {"type": "array", "items": {"type": "object", "properties": {"body_font": {"type": "string"}}}}
|
|
},
|
|
}
|
|
assert "pages.body_font" in _named_fields(planted)
|
|
|
|
|
|
def test_the_project_field_names_the_tool_that_actually_makes_a_project(tmp_path: Path) -> None:
|
|
"""Six of them named `ppt_ingest`, which on this route is optional and not first.
|
|
|
|
A model reading "the project, as given to ppt_ingest" and finding no project has
|
|
one place to go, and it is the wrong one: `ppt_ingest` is `required=False` here
|
|
and refuses a deck holding no sources, while `ppt_prepare` is the first required
|
|
stage and the call that creates the directory. Asserted against the route rather
|
|
than against the string, so renaming the entry stage moves the check with it.
|
|
"""
|
|
profile = registry.get(registry.DEFAULT)
|
|
entry = next(stage.tool for stage in profile.stages if stage.required and stage.tool)
|
|
offences = []
|
|
for tool in build_ppt_tools(tmp_path):
|
|
said = ((tool.parameters.get("properties") or {}).get("project") or {}).get("description") or ""
|
|
named = {name for name in profile.tools if name and name != tool.name and name in said}
|
|
if named - {entry}:
|
|
offences.append(f"{tool.name}.project points at {sorted(named - {entry})} rather than {entry}")
|
|
assert not offences, "\n ".join(["a project field names the wrong tool:", *offences])
|
|
|
|
|
|
def test_the_view_budget_reaches_both_sides_of_the_call_from_one_setting(tmp_path: Path) -> None:
|
|
"""`tools.ppt.viewsPerCall` has to arrive as one number, not as two that agree.
|
|
|
|
It was two hardcoded constants, 1 in the tool and 3 in the stage, and the tool's
|
|
won: a nineteen-page deck took nineteen builds to look at once. Assembly is where a
|
|
setting becomes a stage, so this is where a knob that is declared and never read
|
|
would show -- the failure this module's docstring is about.
|
|
"""
|
|
from raven_ppt.stages.build import BATCH_VIEWS
|
|
|
|
for wanted in (1, 3, 7):
|
|
build = next(t for t in build_ppt_tools(tmp_path, views_per_call=wanted) if t.name == "ppt_build")
|
|
assert build.stage.views_per_call == wanted
|
|
assert build.parameters["properties"]["slides"]["maxItems"] == wanted
|
|
|
|
unset = next(t for t in build_ppt_tools(tmp_path) if t.name == "ppt_build")
|
|
assert unset.stage.views_per_call == BATCH_VIEWS
|
|
|
|
|
|
def test_the_configured_default_is_the_one_the_stage_ships_with() -> None:
|
|
"""Two spellings of the same default, so they get a test rather than a comment.
|
|
|
|
`renderDpi` spells 144 in the slice, in assembly and in `DeckViews`, and nothing
|
|
checks that those stay the same number. This one is load-bearing in a way that one
|
|
is not: it is the batch size the unseen gate is written from, so a slice default
|
|
that drifted from the stage's would change what a deck must show to publish.
|
|
"""
|
|
from raven_ppt.plugin.config import EngineConfig
|
|
from raven_ppt.stages.build import BATCH_VIEWS
|
|
|
|
assert EngineConfig().views_per_call == BATCH_VIEWS
|
|
|
|
|
|
def test_a_view_budget_outside_the_range_is_refused_not_silently_clamped() -> None:
|
|
"""Zero renders would publish a deck nobody looked at; the gate reads the same
|
|
number, so it would also record nothing and refuse forever. Above twelve the reply
|
|
approaches the content-block ceiling an endpoint has already refused. The fork
|
|
said this with a pydantic range on tools.ppt; the plugin slice says it in
|
|
EngineConfig.from_slice, whose raise the factories turn into the fail-closed
|
|
sentinel hook (tests/test_ppt_engine_plugin.py pins that seat)."""
|
|
from raven_ppt.plugin.config import EngineConfig
|
|
|
|
assert EngineConfig.from_slice({"viewsPerCall": 12}).views_per_call == 12
|
|
assert EngineConfig.from_slice({"readerEffort": "low"}).reader_effort == "low"
|
|
assert EngineConfig.from_slice({}).reader_effort == "", "empty means the provider's own default"
|
|
with pytest.raises(ValueError):
|
|
EngineConfig.from_slice({"readerEffort": 3})
|
|
for bad in (0, -1, 13):
|
|
with pytest.raises(ValueError):
|
|
EngineConfig.from_slice({"viewsPerCall": bad})
|
|
|
|
|
|
def test_the_image_generator_answers_configured_from_the_live_host_section(tmp_path: Path, monkeypatch) -> None:
|
|
"""Same terms as the host's image_generate, asked live rather than at assembly:
|
|
the tool is always built, and `configured()` follows the section the reader
|
|
answers with now -- a key or a model offers it, an emptied section withdraws
|
|
it, and an ambient OPENROUTER_API_KEY alone does not offer it."""
|
|
from raven.config.schema import MediaToolConfig
|
|
|
|
monkeypatch.setenv("OPENROUTER_API_KEY", "ambient-chat-key")
|
|
section: dict[str, MediaToolConfig | None] = {"now": None}
|
|
tools = {t.name: t for t in build_ppt_tools(tmp_path, image_config=lambda: section["now"])}
|
|
generator = tools["ppt_generate_image"]
|
|
assert generator.configured() is False
|
|
section["now"] = MediaToolConfig()
|
|
assert generator.configured() is False, "an OpenRouter key set for chat must not switch on a tool that bills"
|
|
section["now"] = MediaToolConfig(api_key="k")
|
|
assert generator.configured() is True and generator.model == "openai/gpt-image-2.5-sunburst"
|
|
section["now"] = MediaToolConfig(model="qwen/qwen-image-2")
|
|
assert generator.configured() is True and generator.model == "qwen/qwen-image-2"
|
|
section["now"] = MediaToolConfig()
|
|
assert generator.configured() is False
|
|
assert "ppt_generate_image" in {t.name for t in build_ppt_tools(tmp_path)}, "built even with no reader lent"
|
|
|
|
|
|
def test_the_render_gate_follows_the_box_and_an_operators_number_still_wins() -> None:
|
|
"""An absent renderConcurrency is a question about the machine, not a default.
|
|
|
|
The fork spelled 2 and the shipped product spelled it after it, so every box
|
|
ran two conversions at once -- measured on 32 cores, seven templates take
|
|
50.3s seven-wide against 67.8s two-wide with the slowest single conversion
|
|
unchanged, so the fixed number was a 32-core box waiting for a two-core box's
|
|
answer. The slice no longer spells it (the launcher ledger pins that), which
|
|
makes this default the one the product actually runs on; a setting that is
|
|
written still wins, and the range is still refused rather than clamped.
|
|
"""
|
|
from raven_ppt.plugin.config import EngineConfig
|
|
from raven_ppt.services.render import default_concurrency
|
|
|
|
assert EngineConfig().render_concurrency == default_concurrency()
|
|
assert EngineConfig.from_slice({}).render_concurrency == default_concurrency()
|
|
assert EngineConfig.from_slice({"renderConcurrency": 1}).render_concurrency == 1
|
|
assert EngineConfig.from_slice({"renderConcurrency": 8}).render_concurrency == 8
|
|
for bad in (0, 9, -1):
|
|
with pytest.raises(ValueError):
|
|
EngineConfig.from_slice({"renderConcurrency": bad})
|
|
|
|
|
|
def test_the_stage_and_the_slice_read_the_same_gate() -> None:
|
|
"""The two seats that size the gate, kept on one number.
|
|
|
|
`DeckViews` is built by direct callers (a test, a script, the template tool's
|
|
thumbnails) as well as by assembly, so a stage default left at 2 would keep
|
|
half the callers on the old fixed number while the product moved.
|
|
"""
|
|
from raven_ppt.plugin.config import EngineConfig
|
|
from raven_ppt.services.render import default_concurrency
|
|
from raven_ppt.stages._views import DeckViews
|
|
|
|
assert DeckViews().concurrency == default_concurrency() == EngineConfig().render_concurrency
|