Initial Commit

openspec/archive/2026-04-19-enterprise-domain-normalizer/proposal.md

@@ -0,0 +1,45 @@
+# OpenSpec Change: enterprise-domain-normalizer
+
+- **Change ID**: enterprise-domain-normalizer
+- **Package**: `@suaveplan/domain-normalizer`
+- **Category**: universal
+- **Target path**: `universal/data/domain-normalizer`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/domain-normalizer.md`
+
+## Summary
+Normalisation, matching, and alias-canonicalisation for internet domain names. Given heterogeneous URL/domain input (including common aliases such as `m.youtube.com → youtube.com`), produces a canonical registrable domain and computes similarity scores for deduplication.
+
+## Current-state audit (genesis)
+Package does not exist yet — fresh build.
+
+## Dependencies
+- Workspace: none (leaf)
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`, `tldts` (public-suffix resolution) — appropriate catalogs
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+### Normaliser
+- `normalizeDomain(input, config?)`, `normalizeUrl(url, config?)`
+- `getRegistrableDomain(input)`, `getSubdomain(input)`, `getDomainGroup(input)`
+
+### Aliases
+- `BUILT_IN_ALIASES`, `getAliasGroup`, `getCanonicalDomain`, `isKnownAlias`, `resetAliasCache`
+
+### Matcher
+- `matchDomains(a, b, config?)`, `computeSimilarity(a, b)`, `findMatchingDomains`, `groupDomains`, `levenshteinDistance`
+
+### Types
+`DomainAliasGroup`, `DomainMatch`, `DomainMatchReason`, `NormalizedUrl`, `NormalizerConfig`
+
+## New genesis additions
+- Codes: `DOMAIN_NORMALIZER.INVALID_INPUT`, `DOMAIN_NORMALIZER.PSL_LOOKUP_FAILED`.
+- Zod schemas for `NormalizerConfig`, `DomainAliasGroup`, `NormalizedUrl`.
+- OTel counter `domain_normalizer.normalize.total{outcome}`, histogram `domain_normalizer.normalize.duration_ms`.
+- Property tests: normalise is idempotent; `getRegistrableDomain` is a fixed point under repeated application.
+
+## Impact
+- Adds one new package: `universal/data/domain-normalizer`
+- Adds one new spec capability: `domain-normalizer`

openspec/archive/2026-04-19-enterprise-domain-normalizer/specs/domain-normalizer/spec.md

@@ -0,0 +1,30 @@
+# Capability Spec: domain-normalizer
+
+**Package**: `@suaveplan/domain-normalizer`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### DN-01 — Normalisation contract
+`normalizeDomain(input)` MUST lowercase, trim, strip leading `www.`, strip port, and apply punycode conversion for IDNs. For any valid input, `normalizeDomain(normalizeDomain(x))` MUST equal `normalizeDomain(x)`.
+
+### DN-02 — Registrable domain via PSL
+`getRegistrableDomain(input)` MUST return the domain at the public-suffix+1 level using the Public Suffix List via `tldts`. For `a.b.co.uk` → `b.co.uk`. Invalid inputs MUST return `undefined`, not throw.
+
+### DN-03 — Alias canonicalisation
+`getCanonicalDomain(input)` MUST resolve built-in aliases (e.g. `m.youtube.com`, `youtu.be` → `youtube.com`) plus any aliases registered via `config.customAliases`. `isKnownAlias` MUST return `true` iff the input matches any alias rule. `resetAliasCache` MUST clear any memoisation.
+
+### DN-04 — Similarity
+`computeSimilarity(a, b)` MUST return a value in `[0, 1]` combining normalised Levenshtein distance and PSL-level registrable-domain equality. `levenshteinDistance` MUST be a standard O(|a|·|b|) implementation.
+
+### DN-05 — Match result
+`matchDomains(a, b, config?)` MUST return `DomainMatch { matched, reason, score }`. `reason` MUST be one of `'exact' | 'alias' | 'registrable-equal' | 'similarity' | 'none'`.
+
+### DN-06 — URL parsing
+`normalizeUrl(url)` MUST return `NormalizedUrl { protocol, host, port?, pathname, search, hash, registrableDomain, subdomain, canonicalDomain }`. Malformed URLs MUST surface as `DOMAIN_NORMALIZER.INVALID_INPUT`.
+
+### DN-07 — Observability
+Every normalisation MUST emit `domain_normalizer.normalize.total{outcome}` counter and `domain_normalizer.normalize.duration_ms` histogram.

openspec/archive/2026-04-19-enterprise-domain-normalizer/tasks.md

@@ -0,0 +1,29 @@
+# Tasks: enterprise-domain-normalizer
+
+## 1. Scaffold
+- [x] 1.1 `universal/data/domain-normalizer/` skeleton; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+- [x] 2.1 `src/errors/*.ts` — codes.
+- [x] 2.2 Zod schemas.
+
+## 3. Aliases
+- [x] 3.1 `src/core/aliases/aliases.ts` — `BUILT_IN_ALIASES` (curated list: m./mobile./amp./lite./www. → canonical), cache + reset.
+
+## 4. Normaliser
+- [x] 4.1 `src/core/normalizer/normalizer.ts` — `normalizeDomain`, `normalizeUrl`, `getRegistrableDomain` (via `tldts`), `getSubdomain`, `getDomainGroup`.
+- [x] 4.2 Idempotency property tests.
+
+## 5. Matcher
+- [x] 5.1 `src/core/matcher/matcher.ts` — `matchDomains`, `computeSimilarity`, `findMatchingDomains`, `groupDomains`, `levenshteinDistance`.
+- [x] 5.2 Property test: `levenshteinDistance(a,a) === 0`; triangle inequality.
+
+## 6. Co-located `.md` + unit tests per module
+
+## 7. Barrel / subpath exports / README
+
+## 8. Benchmarks
+- [x] 8.1 `normalize.bench.ts`, `matcher.bench.ts` on 10 k domain fixture.
+
+## 9. Ship gate
+- [x] 9.1 Verification sequence; fold spec + archive.