Skip to content

docs: document the seam and record the polish gates - #15

Merged
tyrsson merged 8 commits into
1.0.xfrom
tyrsson-render-07-polish
Nov 13, 2026
Merged

tyrsson merged 8 commits into
1.0.xfrom
tyrsson-render-07-polish

Conversation

@tyrsson

@tyrsson tyrsson commented Nov 13, 2026

Copy link
Copy Markdown
Member

Scope

Phase 7 of specs/001-document-view-render/tasks.md: T036 to T043, the polish phase. It lands documentation plus the recorded gate evidence; no production code changes.

Tasks

Task Outcome
T036 mago format --check and mago lint --ignore-baseline clean
T037 mago analyze --ignore-baseline and mago guard clean, no baseline entries added
T038 composer test 84 tests / 145 assertions, composer test-integration 19 tests / 117 assertions, composer test-coverage 100 percent classes, methods and lines (23/23, 60/60, 190/190)
T039 vendor/bin/infection 130 mutants, 127 killed, 3 escaped, MSI 97.69 percent against the 95 gate
T040 roave-backward-compatibility-check --from=origin/1.0.x: one break, the accepted deletion below
T041 README.md: how the seam works, the override recipe, resolution order, failure behaviour
T042 Quickstart scenarios 1 to 6 walked, outcomes below
T043 Sweep for dashes, line endings and naming suffixes, clean

T039, the three escaped mutants

  • EnvironmentFactory.php:93 integer 10 to 9 and 10 to 11. Both still sort ahead of the core DocumentRenderer at priority 0, so no ordering a caller can observe changes. Killing them would mean registering a competing renderer at a contrived priority.
  • Page.php:201 default $overwrite = false to true. The method throws immediately, so the default is unreachable. Equivalent mutant.

T040, the accepted break

Class CommonDoc\Middleware\LayoutWrappingMiddleware has been deleted, approved as settled decision 6 of the feature. The tool cannot run inside a git worktree, because it asserts that .git is a directory and a worktree keeps .git as a file. It was run in a temporary clone of this branch with vendor junctioned, and the clone was removed afterwards. After reporting the removal the tool exits non-zero with a Psl\Process\StartFailedException while starting a follow-up process; that is an environment failure of the tool, not a second difference in the API.

T042, quickstart outcomes

Scenario Evidence
1, body renders through a real view wrapsThePackagedBodyInTheLayout: the body appears inside the layout markers
2, a view helper works inside the body rendersAHelperContributedRegionInsideTheBody: headLink output lands in the body
3, a site overrides the body template by configuration alone rendersTheBodyTemplateTheSiteConfigures: a site map entry wins, the packaged template returns when it is removed
4, a render with no page succeeds rendersADocumentWithNoPagePresent: no exception, empty title region
5, many documents in one process stay independent rendersEachDocumentWithOnlyItsOwnContent: ten documents, no cross-contamination
6, the retired middleware is gone pipeline, factories map, src, test, config and templates contain no reference and no file

The five matching tests run together: 5 tests, 90 assertions.

T043, the sweep

  • 38 files changed against 1.0.x, zero em dashes and zero en dashes.
  • No CRLF in changed files or in specs/001-document-view-render.
  • No *Holder, *Manager, *Helper, *Util or *Service in anything this feature created. The single *Manager match is the pre-existing, untouched ExtensionPluginManager.

Stack

This branch sits on the rebased stack: phase 2 gained the commit that removes the unused IteratorAggregate import, and phases 3 to 7 were rebased onto it so every pull request is green on its own tree.

tyrsson and others added 8 commits November 12, 2026 19:23
…straint

The document view seam imports Mezzio\Template\TemplateRendererInterface directly, so the package that provides it becomes a direct requirement instead of an accident of webware-theme's tree. The php constraint now covers 8.6 while config.platform.php stays pinned at 8.4.99.

Baseline gates recorded before any code change: mago format --check, lint, analyze and guard exit zero, 43 unit tests and 8 integration tests pass.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Joey Smith <jsmith@webinertia.net>
Page implements Laminas\View\Model\ModelInterface for the state a template
reads, never for a position in the render tree: it is final readonly and every
mutator throws, because LaminasViewRenderer writes to the model it renders and
walks children through beforeRender().

PageContext holds the current page for one conversion. PageContextListener
copies it into the document data under commondoc.page on
DocumentPreRenderEvent, so the renderer reads the page from the document it
belongs to and a document built outside a build simply has no entry.

Both factories are registered in ConfigProvider, and the aliases docblock now
says interface-string because its only key is an interface.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Joey Smith <jsmith@webinertia.net>
Page implements ModelInterface and returns an ArrayIterator, so the
IteratorAggregate import was never referenced. Mago reports it as
no-redundant-use on both supported PHP versions, which fails the lint gate
and skips the suites behind it.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add DocumentViewRenderer, registered for the document node at priority 10, so a
converted document is rendered as a view instead of as finished HTML. The body
comes from the injected child renderer and is handed to the template renderer
once, which keeps the layout wrap, the view helpers and the helper state reset
with the framework.

- src/View/DocumentViewRenderer.php, src/Container/DocumentViewRendererFactory.php
- templates/commondoc/layout.phtml as the shell, templates/commondoc/document.phtml
  rewritten as the body template reading documentBody and the optional page
- ConfigProvider: templates.map for commondoc::document and commondoc::layout,
  templates.layout, renderer factory entry, middleware pipeline entry removed
- EnvironmentFactory: renderer at priority 10 and the page context listener on
  the pre-render event
- LayoutWrappingMiddleware, its factory and both tests deleted (owner approved)
- config/autoload/commonmark.global.php: external_link.noFollow was 'none',
  which the CommonMark extension rejects; it is now '' (apply to none)

Tests cover T015 to T027: renderer and factory units, layout and body templates,
the provider wiring, the environment factory registrations and a real container
render asserting the site override, the packaged body with the layout wrap and
the template-not-found failure.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
User story 2 is a property of the seam, so these cases exist to fail if a future
refactor reintroduces HTML post-processing.

- DocumentViewRendererTest: the child renderer is asked once, for exactly the
  document's children; the body reaches the template byte for byte; an empty
  child result still produces a rendered document
- DocumentViewRenderingTest: a body template calling a stateful Laminas helper
  renders that helper's markup inside the body; a table, contributed by the
  installed table extension, reaches the output; the converter is the library's
  own MarkdownConverter and the library's document renderer still sits behind
  the view renderer at the lower priority

Covers T028, T029 and T030.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
A render outside a build has no page, so the null case is now a declared
outcome rather than an assumption.

- DocumentViewRenderer::pageFor returns Page|null, reads commondoc.page with a
  null default and narrows the result, so a document whose entry is absent, null
  or not a page all render the same way
- the page variable is supplied on every render, with no branch that throws or
  short-circuits when it is null
- unit cases for the absent, explicitly null and not-a-page entries
- an integration case that converts with an empty PageContext and asserts a full
  document, body plus layout, with an empty title region

Covers T031, T032 and T033.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
One renderer serves a whole build, so these cases exist to fail if per-render
state ever gets cached in the seam.

- unit: two sequential renders of different documents produce their own bodies,
  the first carries no page and the second carries its own, and the template
  renderer is called exactly once per document
- integration: ten documents through one container and one renderer, each with
  its own heading, body and page label, and no output carrying an earlier
  label

Covers T034 and T035.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
Record how a document reaches the view: the document renderer at priority
10, the two template names ConfigProvider registers, the variables each
receives, and why the body template must never set `content`.

Add the configuration-only override recipe, because the template map is the
mechanism a site uses to replace commondoc::document with no code change,
along with the webware-theme resolution order and the failure behaviour of
a template name that resolves to nothing.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@tyrsson
tyrsson merged commit 2e441a5 into 1.0.x Nov 13, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant