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>
4.9 KiB
4.9 KiB
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.tsandweb/src/seo.test.ts. NocontactPage()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 installinweb/(fresh worktree has nonode_modules; lockfile unchanged), thenpnpm test -- src/seo.test.tsto confirm the baseline is green. - Step 2 —
WebPageTypeandwebPage()inweb/src/seo.ts, next toaboutPage()(implemented generic overextra,webPage<Extra extends object>(...), so fields likemainEntitystay 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,@idandurl(bothcanonicalUrl(path)),nameanddescriptionfromsitePages[path],inLanguage: 'nl-NL', then...extra.- Short English comment in the style of the surrounding code.
- Step 3 — Rebuild
aboutPage()onwebPage(): 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(newdescribe('webPage')):- builds a
ContactPagefor/contactwith the registry's title and description,inLanguageand the canonical URL as both@idandurl; - extra fields appear in the output (
mainEntity,about); - existing
aboutPagetests stay unchanged and pass.
- builds a
- 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],@contextandinLanguagefixed. - Invariant: every key of an arbitrary
extraobject (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.constantFromoverObject.keys(sitePages)and the type list; reuseanySiteContent. Add a shared arbitrary tosrc/test/arbitraries.tsonly if needed by more than this file (expected: not needed, keeping the unit to two files).
- Invariant: for every registered path and every
- Step 6 — Verify (Step 13.5):
pnpm test(incl. the 100% coverage threshold forseo.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.tsandweb/src/seo.test.ts; the docs go in a separate commit. Pushfeature/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" (onlyweb/src/seo.ts,web/src/seo.test.ts).