Initial Commit

openspec/archive/2026-04-19-enterprise-sitemap/proposal.md

@@ -0,0 +1,60 @@
+# OpenSpec Change: enterprise-sitemap
+
+- **Change ID**: enterprise-sitemap
+- **Package**: `@suaveplan/sitemap`
+- **Category**: universal
+- **Target path**: `universal/platform/sitemap`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/sitemap.md`
+
+## Summary
+
+Greenfield rebuild of `@suaveplan/sitemap` — RFC-compliant XML sitemap generator + parser with image, video, and news extensions; sitemap-index generator for sites > 50 k URLs; incremental builder with hash-based change detection; gzip compression with `Content-Encoding` headers; structured errors.
+
+## Current-state audit (genesis)
+
+Package does not exist yet — fresh build.
+
+## Dependencies
+
+- Workspace: `@suaveplan/error`, `@suaveplan/types`
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`, `fflate` (compression), `fast-xml-parser`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+### Generator / parser
+
+- `SitemapGenerator`, `SitemapIndexGenerator`
+- Types: `SitemapOptions`, `SitemapUrl`, `SitemapImage`, `SitemapVideo`, `SitemapNews`, `SitemapIndex`, `ChangeFreq`, `RobotsRule`, `VALID_CHANGE_FREQS`, `SitemapIndexConfig`, `SitemapIndexResult`, `SubSitemap`
+
+### Extensions
+
+- Images: `addImagesToUrl`, `addImagesToUrlSet`, `countImages`, `createImageEntry`, `extractImageUrls`, `removeImagesFromUrl`, `validateImageData`, `validateImageSet`
+- Videos: `addVideosToUrl`, `addVideosToUrlSet`, `countVideos`, `createVideoEntry`, `extractVideoTitles`, `removeVideosFromUrl`, `validateVideoData`
+
+### Incremental
+
+- `IncrementalBuilder`, `computeUrlHash`, `IncrementalBuilderConfig`, `UrlChangeRecord`, `ChangeDetectionMode`, `ChangeDetectionResult`
+
+### Compression
+
+- `compressSitemap`, `decompressSitemap`, `estimateCompressedSize`, `formatSize`, `generateCompressionHeaders`
+- Types: `CompressionHeaders`, `CompressionResult`, `SizeEstimate`
+
+### Errors
+
+- `SitemapError`, `SitemapErrorCode`, `SitemapErrorContext`, `SITEMAP_ERROR_METADATA`, `registerSitemapErrorCodes`
+- `emptyUrls`, `fetchFailed`, `invalidChangeFreq`, `invalidPriority`, `invalidUrl`, `parseFailed`, `tooLarge`
+
+## New genesis additions
+
+- Zod schemas for every URL / image / video shape.
+- OTel histograms `sitemap.generate.duration_ms`, `sitemap.parse.duration_ms`; counter `sitemap.urls.total`.
+- Property tests: build → compress → decompress → parse yields identical URL set.
+
+## Impact
+
+- Adds one new package: `universal/platform/sitemap`
+- Adds one new spec capability: `sitemap`