Duolith docs

0099. Paths written as text are checked when the app is built

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only)
  • Planning item: none

Context

Mik asked for static checks of anything that is known when the app is built and would fail when it runs. An audit (docs/explanation/types.md, "Compile-time safety") found these were already caught: an unknown element, attribute or event (E0101, E0102), an unknown class or theme token (E0103), an unknown icon, role, kit part or piece (E0123 to E0128), a link with a refused scheme (E0170), and, with decision 0096, an import of a module that does not exist (E0347). Two were not: a link to a page that does not exist, and an image from public/ that is not there. Both showed only when someone pressed the link or looked at the image.

Decision

duolith check, duolith build and duolith dev compare every path from the site root written as text with what the build serves (crates/cli/src/links.rs):

  • E0353: a route written as text must name a route a page serves, or a file in public/. That is an href="/..." or href={"/..."} on any element or component; a navigate(...) call, in the script or in a markup expression, under any name it is imported as (import { navigate as go }) or through the namespace (client.navigate); a redirect a guard(...) returns; and the path given to signIn.required(...). The path is a string or a template literal with no ${}. A query and a fragment are ignored. /post/7 matches pages/post/[id].duo, and /docs/a/b matches pages/docs/[...topic].duo.
  • E0354: a src="/..." or src={"/..."} must name a file in public/.

Only text is checked: a path written where it is used, or held in a top-level const of the script (const home = "/", or a property of const routes = { home: "/" } as const), reported where the const is written. A name is resolved by scope, so a parameter, a local or a list's item that has a const's name is not that const. A path built from data or joined from parts, href={post.link} or "/post/" + id, is checked when it is followed, by the router's not-found screen and by the link rules of decision 0040. The two examples that show the not-found screen on purpose join their path from parts, with a comment saying why.

Alternatives considered

OptionWhy not
Type href as a union of the project's routes in the script viewRoutes have parameters (/post/${id}); a template-literal union would make every link's type error unreadable, and data-built paths would need casts
A warning instead of an errorMik asked for loud failures; a warning in a build log is not seen
Check relative paths (href="settings") tooTheir meaning depends on the screen they are shown from, which a layout or a component cannot know

Consequences

The CLI reads every page's script for navigate calls; crates/script-view reports them, so the oxc parse stays in one crate. A repeated key in a list is not checked: keys come from data (key={post.id}), which the build cannot see. It stays in the list of what is out of scope in docs/explanation/types.md.