Repository navigation
docs: document the seam and record the polish gates - #15
Merged
Merged
Conversation
…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 Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
mago format --checkandmago lint --ignore-baselinecleanmago analyze --ignore-baselineandmago guardclean, no baseline entries addedcomposer test84 tests / 145 assertions,composer test-integration19 tests / 117 assertions,composer test-coverage100 percent classes, methods and lines (23/23, 60/60, 190/190)vendor/bin/infection130 mutants, 127 killed, 3 escaped, MSI 97.69 percent against the 95 gateroave-backward-compatibility-check --from=origin/1.0.x: one break, the accepted deletion belowREADME.md: how the seam works, the override recipe, resolution order, failure behaviourT039, the three escaped mutants
EnvironmentFactory.php:93integer 10 to 9 and 10 to 11. Both still sort ahead of the coreDocumentRendererat priority 0, so no ordering a caller can observe changes. Killing them would mean registering a competing renderer at a contrived priority.Page.php:201default$overwrite = falsetotrue. 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.gitis a directory and a worktree keeps.gitas a file. It was run in a temporary clone of this branch withvendorjunctioned, and the clone was removed afterwards. After reporting the removal the tool exits non-zero with aPsl\Process\StartFailedExceptionwhile starting a follow-up process; that is an environment failure of the tool, not a second difference in the API.T042, quickstart outcomes
wrapsThePackagedBodyInTheLayout: the body appears inside the layout markersrendersAHelperContributedRegionInsideTheBody:headLinkoutput lands in the bodyrendersTheBodyTemplateTheSiteConfigures: a site map entry wins, the packaged template returns when it is removedrendersADocumentWithNoPagePresent: no exception, empty title regionrendersEachDocumentWithOnlyItsOwnContent: ten documents, no cross-contaminationsrc,test,configandtemplatescontain no reference and no fileThe five matching tests run together: 5 tests, 90 assertions.
T043, the sweep
1.0.x, zero em dashes and zero en dashes.specs/001-document-view-render.*Holder,*Manager,*Helper,*Utilor*Servicein anything this feature created. The single*Managermatch is the pre-existing, untouchedExtensionPluginManager.Stack
This branch sits on the rebased stack: phase 2 gained the commit that removes the unused
IteratorAggregateimport, and phases 3 to 7 were rebased onto it so every pull request is green on its own tree.