Skip to content

fix(cli): say when a site declaration is not being read - #12

Merged
adammharris merged 1 commit into
mainfrom
agent/backlog-unread-site-declaration
Oct 21, 2026
Merged

adammharris merged 1 commit into
mainfrom
agent/backlog-unread-site-declaration

Conversation

@adammharris

Copy link
Copy Markdown
Member

What changed

  • Export entries carrying render keys. plates-cli's new unread_export_keys reads exports: off every surface prov reads it from (the root's prov: block, the workspace node, the config document). It warns for each index, front_page, shell, stylesheet, style, lang, syntaxes, header or footer on an entry. The warning names the key, the term node it belongs on (site.<key>, or front_page:), and what the site was built with instead.
  • A vocabulary with no term node. read_term_config warns once when the gate field's vocabulary is a flat terms: store (fix: point the field at an index of term documents). It warns once, with different wording, when the vocabulary is reified but has no node for the gate's value (fix: add a node for the term). A pointer that resolves to nothing is still left to prov check.
  • A synthesized front page. A site read off exports: that has no front page, no term node, and a root its audience can't see is reported as anchored at the archive root with a synthesized index. This only fires when the site declared something render-facing: a vocabulary on its gate field, or one of the keys above.
  • An archive that declares nothing render-facing still gets no warnings.
  • The task is marked status: done with a status note.

Why

Before this, a site whose render config sat somewhere plates doesn't look built silently in the built-in shell. The output looked like a correct one-entry site, so nothing pointed at the declaration. This is the repro from the task.

Closes docs/tasks/unread-site-declaration.md.

Verification

  • New tests:
    • term::tests: no vocabulary is silent; a flat store warns; a reified vocabulary with no node warns differently; a found node is silent.
    • build::tests::a_declaration_plates_is_not_reading_is_named: the task's repro, built end to end from disk.
    • an_archive_that_declares_no_render_config_hears_nothing.
    • a_site_fronted_by_its_term_node_hears_nothing.
  • The two term warning tests failed before the fix.
  • Ran the task's repro through plates build. On main it prints only ✓ diaryx — 2 pages. On this branch it prints the two unread-key warnings, the flat-store warning and the front-page note.
  • ship ci: all 7 jobs passed (fmt, clippy, test, docs, wasm, alone, msrv). prov check finds nothing.

Open questions

  • The task's last two "Done when" bullets pull against each other: "report a site with no front page" versus "an archive that declares nothing render-facing stays silent". I reconciled them by reporting the synthesized front page only for a site that declared something render-facing. A gate field with any vocabulary counts as render-facing.
  • So an archive with a flat closed audience vocabulary and no render config now gets the flat-store warning on every build. The task asks for that, but say if it is too noisy.

A site whose render-facing declaration plates could not see built anyway,
in silence, and the result looked like a rendering bug. Render keys on an
`exports.<name>` entry (`shell`, `stylesheet`, `lang`, `syntaxes`,
`index`, `front_page` and the rest of a term node's `site:` keys) are now
named with where they belong and what the site fell back to.
`read_term_config` warns when the gate field's vocabulary is a flat
`terms:` store, and separately when a reified one has no node for the
gate's value. A site with no front page from any source is reported as
anchored at the archive root with a synthesized index. An archive that
declares nothing render-facing still hears nothing.

Closes docs/tasks/unread-site-declaration.md.

Behavioural-change: `plates build` and `plates serve` print new warnings for an archive whose export entries carry render keys, whose gate field's vocabulary is flat or has no node for the gate's value, or whose site has no front page while declaring something render-facing; `read_term_config` returns a warning in `TermConfig::warnings` for the flat and missing-node cases where it used to return none.
@adammharris
adammharris merged commit 00fb3cf into main Oct 21, 2026
8 checks passed
@adammharris
adammharris deleted the agent/backlog-unread-site-declaration branch October 30, 2026 01:25
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