Files
AndreaSlopFotografie/aidlc-docs/features/contact-page/construction/plans/webpage-helper-code-generation-plan.md
T
SluijsensandClaude Opus 5.5 4c257b7ac0 Plans the Contact page and records unit 1 as generated
Workspace detection, a reverse engineering delta, requirements with the
approved layout mockups, the execution plan and the application design
for the Contact page, plus the code generation plan and summary of the
webPage helper. Corrects the contact payload in the shared API notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 16:59:38 +01:00

4.9 KiB
Raw Blame History

Code Generation Plan — Unit 1: webPage helper

Single source of truth for generating unit 1. Workspace root: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-contact (worktree), code in web/. Branch feature/contact-page.

Unit context

  • Requirements: SEO-CP-03 (helper part); NFR-CP-03 (PBT); coordination agreement with portfolio-page and soorten-fotoshoots-page.
  • Design: component-methods.md § seo.ts; PBT-01 properties in application-design.md.
  • Scope boundary: only web/src/seo.ts and web/src/seo.test.ts. No contactPage() yet (unit 3), no other files, so other branches can cherry-pick this commit cleanly.
  • Dependencies: none. Depended on by: unit 3 (contactPage()), portfolio-page, soorten-fotoshoots-page.

Steps

  • Step 1 — Prepare the worktree: pnpm install in web/ (fresh worktree has no node_modules; lockfile unchanged), then pnpm test -- src/seo.test.ts to confirm the baseline is green.
  • Step 2 — WebPageType and webPage() in web/src/seo.ts, next to aboutPage() (implemented generic over extra, webPage<Extra extends object>(...), so fields like mainEntity stay typed for callers; call signature unchanged):
    • export type WebPageType = 'WebPage' | 'AboutPage' | 'ContactPage' | 'ImageGallery' | 'CollectionPage';
    • export function webPage(type: WebPageType, path: RoutePath, extra: Record<string, unknown> = {}) returning @context, @type, @id and url (both canonicalUrl(path)), name and description from sitePages[path], inLanguage: 'nl-NL', then ...extra.
    • Short English comment in the style of the surrounding code.
  • Step 3 — Rebuild aboutPage() on webPage(): same signature; webPage('AboutPage', path, { mainEntity: person(content, site, image) }) with the image computed as today. Key order may change; the output must be equal as data.
  • Step 4 — Example tests in web/src/seo.test.ts (new describe('webPage')):
    • builds a ContactPage for /contact with the registry's title and description, inLanguage and the canonical URL as both @id and url;
    • extra fields appear in the output (mainEntity, about);
    • existing aboutPage tests stay unchanged and pass.
  • Step 5 — Property tests (fast-check, PBT-01/03/05):
    • Invariant: for every registered path and every WebPageType, @id = url = canonicalUrl(path), @type = type, name/description = sitePages[path], @context and inLanguage fixed.
    • Invariant: every key of an arbitrary extra object (keys not overlapping the base keys) is present in the output with the same value.
    • Oracle: aboutPage() equals a frozen copy of the previous implementation (kept in the test file) for generated site content (anySiteContent) and the registered paths.
    • Round-trip: JSON.parse(jsonLdScript(webPage(...))) equals the object (extends the existing jsonLdScript property to this builder).
    • Generators: fc.constantFrom over Object.keys(sitePages) and the type list; reuse anySiteContent. Add a shared arbitrary to src/test/arbitraries.ts only if needed by more than this file (expected: not needed, keeping the unit to two files).
  • Step 6 — Verify (Step 13.5): pnpm test (incl. the 100% coverage threshold for seo.ts), pnpm lint, pnpm format:check, pnpm build. Fix and repeat until green. Lighthouse is not affected by this unit (no page output changes) and runs in unit 2/3 and Build and Test.
  • Step 7 — Code summary: aidlc-docs/features/contact-page/construction/webpage-helper/code/code-summary.md (what changed, the agreed signature, test overview).
  • Step 8 — Commit and hand over (after your approval of the generated code): one commit "Adds a generic WebPage structured data helper" containing only web/src/seo.ts and web/src/seo.test.ts; the docs go in a separate commit. Push feature/contact-page, then send the commit hash to portfolio-page and soorten-fotoshoots-page.

Expected interfaces after this unit

export type WebPageType = 'WebPage' | 'AboutPage' | 'ContactPage' | 'ImageGallery' | 'CollectionPage';
export function webPage(type: WebPageType, path: RoutePath, extra?: Record<string, unknown>): {...};
export function aboutPage(path: RoutePath, content: AboutPageContent['person'], site: SiteContent): {...}; // unchanged

Extension compliance (plan level)

  • Security: no new dependencies, endpoints or output; structured data still escaped by jsonLdScript — Compliant.
  • PBT: PBT-02 (round-trip), PBT-03 (invariants), PBT-05 (oracle), PBT-07 (generators from the registry), PBT-08 (seed logging exists), PBT-10 (examples alongside) — Planned in steps 4–5; PBT-04/06 N/A.

Result

  • Code commit: 790495d "Adds a generic WebPage structured data helper" (only web/src/seo.ts, web/src/seo.test.ts).