Skip to content

feat: name every page in a build time router and rewrite prose links - #10

Open
tyrsson wants to merge 10 commits into
1.0.xfrom
tyrsson-verbose-waddle
Open

tyrsson wants to merge 10 commits into
1.0.xfrom
tyrsson-verbose-waddle

Conversation

@tyrsson

@tyrsson tyrsson commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

What this changes

Prose links 404 today: pages render href="./flow-charts.md", only .md sources exist, and
dist/ holds no .md files. Nothing downstream can name a page because no page has a route.

This branch makes webware/query-param-router a build time router. Every document in the
corpus gets exactly one route, registered in a RouteCollector next to a QueryParamRouter,
and the sidebar and the rewritten hrefs both come from that registration.

Corpus (every project, every version, every document)
  -> DocumentRouteProvider  one Route per document
       -> Navigation        sidebar markup
       -> LinkRewriter      rewritten hrefs

Behaviour a reviewer should judge

  • SiteBuild resolves the whole corpus before it renders, so a cross project link and a
    sidebar item cannot depend on write order.
  • SiteRendererInterface::render() takes a TargetCorpus instead of a target. There is no
    deprecated variant: this lands before 1.0.0.
  • The output tree is one .html file per document, with the directory index.html still
    serving its directory.
  • A document that cannot be addressed reports unresolved-links instead of writing a broken
    href. Images are counted and never rewritten.
  • The sidebar comes from webware-navigation, so the markup carries no Bootstrap classes.
  • No route table is published. The router holds the routes in memory for the length of a
    build, and the sidebar and the site index read them from there.

Spec and contracts

spec.md gains FR-023 to FR-028, additive only. contracts/output-tree.md gains rules 12 to
15 (one html file per document, a directory index.html, navigation markup).
contracts/build-report.schema.json gains unresolved-links and a links count block, and
contracts/site-config.schema.json gains the navigation block.

Dependency refresh

webware/webware-tools moves from 1.0.0-rc.14 to the released 1.0.0 in composer.lock
only. The range in composer.json already admitted it, and no other package moves.

tyrsson and others added 6 commits November 14, 2026 09:34
webware/query-param-router provides Webware\Router\RouteProviderInterface, the
Mezzio route provider interface without the MiddlewareFactoryInterface
parameter, so the build does not have to require mezzio/mezzio to name a route
provider.

webware/webware-navigation supplies the sidebar tree and the renderer seam the
page navigation is built on. 1.0.0-alpha.8 is only published as a tag, so the
repository is listed as a VCS repository.

ext-dom is required because the link rewriter parses the rendered page.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The corpus now resolves in full before any page is written. SiteBuild collects
every project, version and document, DocumentRouteProvider registers one named
route per document into the shared RouteCollector and QueryParamRouter, and only
then does the build render project by project. A cross project link or a sidebar
cannot exist before the first page is written, so the split is what makes either
possible.

PageAddressFactory still owns addresses and the router owns names and hrefs.
DocumentRouteProvider::nameFor() derives a name from the target and the document
path alone, so the provider and the link rewriter agree without either holding an
index, and generateUri() throwing for an unknown name is the existence check.

One document is one file. docs/2.0/flow-charts.md publishes to
message-bus/2.0/flow-charts.html, so prose links stop pointing at .md sources
that are never published. A directory index.html still serves its directory.

LinkRewriter rewrites every internal link that names a published document to the
published address, preserving fragment and query. A link naming a document that
was never published is left exactly as written and counted, so a broken link
stays visible instead of becoming a failed page.

The sidebar comes from webware-navigation over the same route table, with the
current page active and the markup owned by DocsSidebarRenderer rather than the
inline Bootstrap default. Because a layout cannot receive page variables, the
markup reaches the layout through a view helper.

Resolve-then-render also removes the previous double read of every source.

SiteRendererInterface::render() now takes a TargetCorpus, per the same split.
navigation.enabled in site.json turns all of it off, and a site that has not
opted in publishes byte for byte what it published before.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
PageLabel, DocumentRouteProvider, LinkRewriter, PageNavigation and the link pass in
TargetRenderer now have the cases the design asks for, plus a shared Targets helper
so each test names its documents rather than restating the corpus plumbing.

DocsSidebarRenderer marks the ancestor chain active and only the current page with
aria-current, which the nesting test found: the container reports an item active
when any of its children is current.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Adds FR-023 to FR-028 to specs/001-aggregate-renderer/spec.md, covering
rewritten links, unresolved links, one named route per page, per page
navigation, full corpus resolution before the first write, and a duplicate
address or route name failing the build.

output-tree.md rules 3 and 4 move from directory addresses to one html file
per document, and rules 11 to 13 cover root absolute hrefs, the directory
index still serving its directory, and the navigation markup.

build-report.schema.json gains the unresolved-links reason code and the
links count block. site-config.schema.json gains the navigation block.

tasks.md named a src/Discovery/DiscoveryFailed.php that does not exist; the
class is src/Exception/DiscoveryException.php.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Split the page rendering path so no constructor, method or call sits above
mago's arity and complexity thresholds: PagePresenter now folds the page
lifetime, LinkRewriter splits into LinkHref and DocumentPath, and the phase
one corpus wiring lives in CorpusRegistration. NavigationReader is extracted
from SiteConfigReader for the same reason.

NoOpMiddleware moves to CommonDoc\Aggregate\Http\Middleware because the fleet
perimeter rule restricts Psr\Http\Server to namespaces containing Http.

Behaviour is unchanged; the suites stay green.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
requireCoverageMetadata means a class that a test exercises but never names
in an attribute reports zero coverage, which is a silent defect rather than a
test gap. Every source class this branch adds is now named, and the container
factories, LinkTotals, the no op middleware and ProjectBuild gain their own
cases. New cases also cover an image beside a link, a page carrying only an
image, a dot segment href, the Section optional bool reader, the direct
NavigationConfig default and a navigation enabled renderer build.

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

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.78683% with 7 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/Discovery/GitHubApi.php 50.00% 6 Missing ⚠️
src/Render/LinkRewriter.php 97.56% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

tyrsson and others added 4 commits November 14, 2026 10:39
webware/webware-navigation is published to Packagist (1.0.0-alpha.8 is
listed by composer show --all), so the vcs entry that pointed at
github.com/webinertia/webware-navigation.git was never needed. Every
version constraint in composer.json resolves from Packagist without it.

The lockfile revision is the only change beyond the deletion: the
repositories key is part of the content hash, so composer.lock records a
new content-hash and nothing else. composer update --lock reports no
installs, no updates and no removals, and composer install reports nothing
to install, update or remove.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The range in composer.json already admitted 1.0.0, so only the lock moves:
rc.14 (8093557) to 1.0.0 (9369090).

Clears what the newer toolchain sees on this branch:

- 100 call sites in src and test now pass the literal argument by name.
- ConfigHash drops a docblock that repeated the inferred type of a local.
- 16 files formatted, all of them files this pass or the earlier feature
  already touched.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
LinkOutcome keeps its four singular cases and gains none, but two of its six
cases were plural. That inconsistency is the whole change: Documents becomes
Document and Anchors becomes Anchor.

The backing strings stay 'documents' and 'anchors', so the report keys and
the contract are untouched. 21 call sites follow the rename.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…y their head noun

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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