Skip to content

scaffold: close the coverage-gate deferred gaps (core + server + convention demos) #859

Description

@vivek7405

Problem

The scaffold teaching-coverage gate added in the coverage-gate PR classifies every @webjsdev/core export as demoed (a runnable gallery example), internal-exempt (framework plumbing), or deferred (agent-facing, but no runnable gallery demo yet). 29 exports are currently deferred. They are real APIs an agent may reach for, so the gallery should teach each with a real, commented demo. Converting a deferred exemption into a { demo } pointer is the intended way to shrink the list (and is the follow-through that makes the gate drive demos, not exemptions).

Deferred set (see test/scaffolds/gallery-coverage.json, reasons carry the doc pointer):
Suspense, css (shadow styles), Task, TaskStatus, computed, effect, batch, createContext, ContextProvider, ContextConsumer, ContextRequestEvent, unsafeHTML, ref, createRef, guard, templateContent, asyncAppend, asyncReplace, until, live, keyed, navigate, redirect, revalidate, richFetch, disableClientRouter, enableClientRouter, cache (lit directive), cspNonce.

Design / approach

Prioritise the highest-frequency agent APIs first, then chip away:

  • Suspense (page-level streaming) and css / shadow-DOM static styles are headline surfaces that deserve their own feature demos.
  • navigate / redirect are currently prose-only in the routing/boundaries demos; give them a runnable button/handler (navigate) and a route (redirect).
  • The lit-parity directives (unsafeHTML, ref/createRef, guard, templateContent, asyncAppend/asyncReplace, until, live, keyed) can extend the existing app/features/directives demo, which today only shows repeat + watch.
  • The signals extras (computed, effect, batch) and the context API (createContext + Context*) fit a components/signals demo.

Each conversion: add the runnable usage to a gallery file (new or existing), then flip that export's entry in gallery-coverage.json from { exempt: "deferred: ..." } to { demo: "<gallery file>" }. The gate verifies the pointed file actually references the symbol.

Implementation notes (for the implementing agent)

  • Manifest + gate: test/scaffolds/gallery-coverage.json (source of truth) and test/scaffolds/gallery-coverage.test.js (the reconcile() gate; the every @webjsdev/core export is demoed or exempted test prints the live deferred list).
  • Gallery demos live under packages/cli/templates/gallery/app/features/<name>/ with logic in .../modules/<name>/; the home index features array is in packages/cli/lib/create.js (two copies: full-stack + saas home), and test/scaffolds/scaffold-gallery.test.js FEATURES asserts each.
  • Follow the webjs-scaffold-sync skill for every surface; each new feature page carries a webjs-scaffold-placeholder marker and dense teaching comments.
  • Landmine: the gate's demo check is a word-boundary match on the symbol, so a demo that only mentions the API in prose still fails unless it truly imports/uses it (that is the point). Respect the prose-punctuation invariant (release: bump core/server/cli versions, honest engines fields #11) in comments.
  • Verify by generating + booting a full-stack app and hitting each new route (webjs check should show only no-scaffold-placeholder).

Acceptance criteria

  • Each converted export has a runnable gallery demo and a { demo } entry in gallery-coverage.json
  • The gate's deferred count drops accordingly; the coverage test stays green
  • scaffold-gallery.test.js asserts any new feature route
  • A freshly generated full-stack app boots and serves each new demo route
  • Docs/scaffold rule-file feature lists updated for any new feature folder

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Fields

No fields configured for issues without a type.

Projects

Status
In progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions