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>
46 lines
4.9 KiB
Markdown
46 lines
4.9 KiB
Markdown
# 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](../../inception/application-design/component-methods.md) § `seo.ts`; PBT-01 properties in [application-design.md](../../inception/application-design/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
|
||
|
||
- [x] **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.
|
||
- [x] **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.
|
||
- [x] **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.
|
||
- [x] **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.
|
||
- [x] **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).
|
||
- [x] **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.
|
||
- [x] **Step 7 — Code summary**: `aidlc-docs/features/contact-page/construction/webpage-helper/code/code-summary.md` (what changed, the agreed signature, test overview).
|
||
- [x] **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
|
||
```ts
|
||
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`).
|