@actuate-media/cms-core 0.28.1 → 0.29.0

package/dist/redirects/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/redirects/graph.ts"],"names":[],"mappings":"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"}

package/dist/redirects/index.d.ts

@@ -0,0 +1,5 @@
+export { normalizeRedirectPath, isExternal, buildEdgeMap, resolveChain, detectChainsAndLoops, wouldCreateLoop, isRedirectStale, } from './graph.js';
+export type { RedirectRecord, ChainResolution, DetectedChain } from './graph.js';
+export { suggestRedirectTarget } from './suggest.js';
+export type { SuggestCandidate, RedirectSuggestionResult } from './suggest.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/redirects/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/redirects/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAA;AAEnB,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEhF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAEpD,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA"}

package/dist/redirects/index.js

@@ -0,0 +1,3 @@
+export { normalizeRedirectPath, isExternal, buildEdgeMap, resolveChain, detectChainsAndLoops, wouldCreateLoop, isRedirectStale, } from './graph.js';
+export { suggestRedirectTarget } from './suggest.js';
+//# sourceMappingURL=index.js.map

package/dist/redirects/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/redirects/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAA;AAInB,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA"}

package/dist/redirects/suggest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 404 recovery suggestions — pure heuristic matching of a dead path to the
+ * best live URL using path-segment + title token similarity. Used as the
+ * always-available baseline; the API can layer AI ranking on top when a
+ * provider is configured.
+ */
+export interface SuggestCandidate {
+    url: string;
+    title?: string;
+}
+export interface RedirectSuggestionResult {
+    toPath: string;
+    confidence: number;
+    reason: string;
+}
+/**
+ * Suggest the best redirect target for a dead `fromPath`. Returns null when no
+ * candidate clears the minimum confidence threshold (default 30).
+ */
+export declare function suggestRedirectTarget(fromPath: string, candidates: SuggestCandidate[], minConfidence?: number): RedirectSuggestionResult | null;
+//# sourceMappingURL=suggest.d.ts.map

package/dist/redirects/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/redirects/suggest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;CACf;AAmBD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,gBAAgB,EAAE,EAC9B,aAAa,SAAK,GACjB,wBAAwB,GAAG,IAAI,CA0BjC"}

package/dist/redirects/suggest.js

@@ -0,0 +1,55 @@
+/**
+ * 404 recovery suggestions — pure heuristic matching of a dead path to the
+ * best live URL using path-segment + title token similarity. Used as the
+ * always-available baseline; the API can layer AI ranking on top when a
+ * provider is configured.
+ */
+function tokens(input) {
+    return input
+        .toLowerCase()
+        .replace(/^https?:\/\/[^/]+/i, '')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 1);
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * Suggest the best redirect target for a dead `fromPath`. Returns null when no
+ * candidate clears the minimum confidence threshold (default 30).
+ */
+export function suggestRedirectTarget(fromPath, candidates, minConfidence = 30) {
+    const fromTokens = new Set(tokens(fromPath));
+    if (fromTokens.size === 0 || candidates.length === 0)
+        return null;
+    let best = null;
+    for (const c of candidates) {
+        const pathTokens = new Set(tokens(c.url));
+        const titleTokens = new Set(tokens(c.title ?? ''));
+        const pathSim = jaccard(fromTokens, pathTokens);
+        const titleSim = jaccard(fromTokens, titleTokens);
+        // Path match weighted higher than title match.
+        const score = Math.round((pathSim * 0.7 + titleSim * 0.3) * 100);
+        if (!best || score > best.confidence) {
+            best = {
+                toPath: c.url,
+                confidence: score,
+                reason: pathSim >= titleSim
+                    ? `URL path similarity to ${c.url}`
+                    : `Title similarity to "${c.title ?? c.url}"`,
+            };
+        }
+    }
+    if (!best || best.confidence < minConfidence)
+        return null;
+    return best;
+}
+//# sourceMappingURL=suggest.js.map

package/dist/redirects/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/redirects/suggest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC;SACjC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;AAChC,CAAC;AAED,SAAS,OAAO,CAAC,CAAc,EAAE,CAAc;IAC7C,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAC1C,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,KAAK,MAAM,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,KAAK,EAAE,CAAA;IACxC,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,KAAK,CAAA;IACrC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAA;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,UAA8B,EAC9B,aAAa,GAAG,EAAE;IAElB,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC5C,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEjE,IAAI,IAAI,GAAoC,IAAI,CAAA;IAChD,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACzC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAA;QAClD,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;QAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC,CAAA;QACjD,+CAA+C;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,GAAG,GAAG,QAAQ,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAA;QAChE,IAAI,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,GAAG;gBACL,MAAM,EAAE,CAAC,CAAC,GAAG;gBACb,UAAU,EAAE,KAAK;gBACjB,MAAM,EACJ,OAAO,IAAI,QAAQ;oBACjB,CAAC,CAAC,0BAA0B,CAAC,CAAC,GAAG,EAAE;oBACnC,CAAC,CAAC,wBAAwB,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG;aAClD,CAAA;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,GAAG,aAAa;QAAE,OAAO,IAAI,CAAA;IACzD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/seo/audit-engine.d.ts

@@ -0,0 +1,119 @@
+/**
+ * SEO audit engine.
+ *
+ * Pure analysis: given a set of content entities (pages/posts) plus optional
+ * cross-cutting signals (broken links, redirect chains/loops, sitemap/robots
+ * health), it produces:
+ *   - per-page SEO scores (via `calculatePageSeoScore`),
+ *   - a flat list of detected issues with stable `issueKey`s,
+ *   - an explainable site score (via `calculateSiteSeoScore`),
+ *   - issue counts by severity, and
+ *   - priority-ranked quick wins.
+ *
+ * The handler layer fetches the data, calls `runSeoAuditAnalysis`, and
+ * snapshots the result into `SeoAuditRun` / `SeoIssue` rows. Keeping detection
+ * pure means it is fully unit-testable with no DB.
+ */
+import { gradeForSeoScore, type SeoGrade, type SiteSeoScoreResult } from './score.js';
+export type SeoSeverity = 'critical' | 'warning' | 'info';
+export type SeoIssueCategory = 'content' | 'technical' | 'redirects' | 'media' | 'performance' | 'schema' | 'social' | 'indexing';
+export interface AuditEntityInput {
+    entityType: 'page' | 'post';
+    entityId: string;
+    title: string;
+    url: string;
+    content?: string;
+    metaTitle?: string | null;
+    metaDescription?: string | null;
+    focusKeyword?: string | null;
+    canonicalUrl?: string | null;
+    ogTitle?: string | null;
+    ogDescription?: string | null;
+    ogImage?: string | null;
+    structuredDataType?: string | null;
+    noindex?: boolean | null;
+    shouldBeIndexable?: boolean;
+    wordCount?: number | null;
+}
+export interface AuditExtraSignals {
+    /** Broken internal links discovered by the link checker. */
+    brokenLinks?: {
+        url: string;
+        fromEntityId: string;
+        fromTitle: string;
+        fromUrl: string;
+    }[];
+    /** Pages flagged as slow by an external performance source. */
+    slowPages?: {
+        entityId: string;
+        title: string;
+        url: string;
+        note?: string;
+    }[];
+    redirectChains?: number;
+    redirectLoops?: number;
+    sitemapEnabled?: boolean;
+    robotsEnabled?: boolean;
+}
+export interface DetectedIssue {
+    issueKey: string;
+    entityType: string | null;
+    entityId: string | null;
+    entityTitle: string | null;
+    url: string | null;
+    severity: SeoSeverity;
+    category: SeoIssueCategory;
+    type: string;
+    title: string;
+    description: string;
+    impact: string;
+    recommendation: string;
+    fixable: boolean;
+    fixActionType: string | null;
+    relatedEntityIds: string[];
+}
+export interface AuditPageRecord {
+    entityType: 'page' | 'post';
+    entityId: string;
+    title: string;
+    url: string;
+    score: number;
+    grade: SeoGrade;
+    metaTitleSet: boolean;
+    metaDescriptionSet: boolean;
+}
+export interface QuickWin {
+    id: string;
+    title: string;
+    explanation: string;
+    impact: 'High' | 'Medium' | 'Low';
+    issueType: string;
+    fixActionType: string | null;
+    count: number;
+}
+export interface SeoAuditResult {
+    pages: AuditPageRecord[];
+    issues: DetectedIssue[];
+    siteScore: SiteSeoScoreResult;
+    counts: {
+        total: number;
+        critical: number;
+        warning: number;
+        info: number;
+    };
+    quickWins: QuickWin[];
+}
+/** Stable per-issue key so status carries across audit runs. */
+export declare function issueKeyFor(type: string, identifier: string): string;
+/**
+ * Run the full SEO audit analysis over a set of entities + signals.
+ */
+export declare function runSeoAuditAnalysis(entities: AuditEntityInput[], signals?: AuditExtraSignals): SeoAuditResult;
+/**
+ * Derive priority-ranked quick wins by grouping issues by type and ranking by
+ * (impact, severity, count). Never hardcoded — purely a function of detected
+ * issues, so the Overview "Quick Wins" card always reflects reality.
+ */
+export declare function buildQuickWins(issues: DetectedIssue[]): QuickWin[];
+export { gradeForSeoScore };
+//# sourceMappingURL=audit-engine.d.ts.map

package/dist/seo/audit-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-engine.d.ts","sourceRoot":"","sources":["../../src/seo/audit-engine.ts"],"names":[],"mappings":"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"}

package/dist/seo/audit-engine.js

@@ -0,0 +1,402 @@
+/**
+ * SEO audit engine.
+ *
+ * Pure analysis: given a set of content entities (pages/posts) plus optional
+ * cross-cutting signals (broken links, redirect chains/loops, sitemap/robots
+ * health), it produces:
+ *   - per-page SEO scores (via `calculatePageSeoScore`),
+ *   - a flat list of detected issues with stable `issueKey`s,
+ *   - an explainable site score (via `calculateSiteSeoScore`),
+ *   - issue counts by severity, and
+ *   - priority-ranked quick wins.
+ *
+ * The handler layer fetches the data, calls `runSeoAuditAnalysis`, and
+ * snapshots the result into `SeoAuditRun` / `SeoIssue` rows. Keeping detection
+ * pure means it is fully unit-testable with no DB.
+ */
+import { calculatePageSeoScore, calculateSiteSeoScore, gradeForSeoScore, countH1, } from './score.js';
+import { stripHtmlTags } from './analysis.js';
+function present(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function normalizeTitle(t) {
+    return t.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function wordsOf(content, fallback) {
+    if (typeof fallback === 'number')
+        return fallback;
+    if (!content)
+        return 0;
+    const text = stripHtmlTags(content);
+    return text ? text.split(/\s+/).filter((w) => w.length > 0).length : 0;
+}
+function countMissingAlt(content) {
+    if (!content)
+        return 0;
+    const imgs = content.match(/<img\b[^>]*>/gi) ?? [];
+    return imgs.filter((img) => !/\balt\s*=\s*["'][^"']+["']/i.test(img)).length;
+}
+/** Stable per-issue key so status carries across audit runs. */
+export function issueKeyFor(type, identifier) {
+    return `${type}:${identifier}`;
+}
+/**
+ * Run the full SEO audit analysis over a set of entities + signals.
+ */
+export function runSeoAuditAnalysis(entities, signals = {}) {
+    const issues = [];
+    const pages = [];
+    // -- Per-entity content checks -------------------------------------------
+    for (const e of entities) {
+        const wordCount = wordsOf(e.content, e.wordCount);
+        const scoreResult = calculatePageSeoScore({
+            title: e.title,
+            url: e.url,
+            content: e.content,
+            metaTitle: e.metaTitle,
+            metaDescription: e.metaDescription,
+            focusKeyword: e.focusKeyword,
+            canonicalUrl: e.canonicalUrl,
+            ogTitle: e.ogTitle,
+            ogDescription: e.ogDescription,
+            ogImage: e.ogImage,
+            structuredDataType: e.structuredDataType,
+            noindex: e.noindex,
+            shouldBeIndexable: e.shouldBeIndexable,
+            wordCount,
+        });
+        pages.push({
+            entityType: e.entityType,
+            entityId: e.entityId,
+            title: e.title,
+            url: e.url,
+            score: scoreResult.score,
+            grade: scoreResult.grade,
+            metaTitleSet: present(e.metaTitle),
+            metaDescriptionSet: present(e.metaDescription),
+        });
+        const ctx = {
+            entityType: e.entityType,
+            entityId: e.entityId,
+            entityTitle: e.title,
+            url: e.url,
+        };
+        if (!present(e.metaTitle)) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('missing-meta-title', e.entityId),
+                severity: 'warning',
+                category: 'content',
+                type: 'missing-meta-title',
+                title: 'Missing meta title',
+                description: 'This page has no meta title. Search engines fall back to the H1 or filename.',
+                impact: 'High',
+                recommendation: 'Add a 30–60 character meta title containing the target keyword.',
+                fixable: true,
+                fixActionType: 'edit-metadata',
+                relatedEntityIds: [],
+            });
+        }
+        if (!present(e.metaDescription)) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('missing-meta-description', e.entityId),
+                severity: 'warning',
+                category: 'content',
+                type: 'missing-meta-description',
+                title: 'Missing meta description',
+                description: 'Add a 150–160 character description summarising the page for search engines.',
+                impact: 'High',
+                recommendation: 'Write a unique meta description that includes the focus keyword.',
+                fixable: true,
+                fixActionType: 'edit-metadata',
+                relatedEntityIds: [],
+            });
+        }
+        if (!present(e.structuredDataType)) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('missing-structured-data', e.entityId),
+                severity: 'warning',
+                category: 'schema',
+                type: 'missing-structured-data',
+                title: 'No structured data found',
+                description: 'Add Schema.org markup to improve rich-result eligibility.',
+                impact: 'Medium',
+                recommendation: 'Choose an appropriate schema type (Article, Product, FAQPage, …).',
+                fixable: true,
+                fixActionType: 'edit-schema',
+                relatedEntityIds: [],
+            });
+        }
+        if (!present(e.canonicalUrl)) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('missing-canonical', e.entityId),
+                severity: 'info',
+                category: 'technical',
+                type: 'missing-canonical',
+                title: 'Missing canonical tag',
+                description: 'Add a canonical tag to prevent duplicate-content issues across URLs.',
+                impact: 'Low',
+                recommendation: 'Set the canonical URL to this page’s preferred public URL.',
+                fixable: true,
+                fixActionType: 'edit-canonical',
+                relatedEntityIds: [],
+            });
+        }
+        if (!present(e.ogImage)) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('missing-og-image', e.entityId),
+                severity: 'info',
+                category: 'social',
+                type: 'missing-og-image',
+                title: 'No OG image set',
+                description: 'Pages without an OG image show a generic placeholder when shared.',
+                impact: 'Low',
+                recommendation: 'Pick or generate an Open Graph image in the social metadata section.',
+                fixable: true,
+                fixActionType: 'edit-og-image',
+                relatedEntityIds: [],
+            });
+        }
+        if ((e.content ?? '').length > 0 && countH1(e.content ?? '') === 0) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('missing-h1', e.entityId),
+                severity: 'info',
+                category: 'content',
+                type: 'missing-h1',
+                title: 'Missing H1 heading',
+                description: 'Every page should have exactly one H1 that includes the target keyword.',
+                impact: 'Low',
+                recommendation: 'Add a single descriptive H1 heading to the content.',
+                fixable: false,
+                fixActionType: 'edit-content',
+                relatedEntityIds: [],
+            });
+        }
+        if (wordCount > 0 && wordCount < 300) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('thin-content', e.entityId),
+                severity: 'info',
+                category: 'content',
+                type: 'thin-content',
+                title: 'Content below 300 words',
+                description: 'Thin pages tend to rank poorly. Consider expanding the copy.',
+                impact: 'Low',
+                recommendation: 'Add more useful content or an FAQ section.',
+                fixable: false,
+                fixActionType: 'edit-content',
+                relatedEntityIds: [],
+            });
+        }
+        const missingAlt = countMissingAlt(e.content);
+        if (missingAlt > 0) {
+            issues.push({
+                ...ctx,
+                issueKey: issueKeyFor('missing-alt-text', e.entityId),
+                severity: 'warning',
+                category: 'media',
+                type: 'missing-alt-text',
+                title: 'Images missing alt text',
+                description: `${missingAlt} image(s) are missing alt text, hurting accessibility and image search.`,
+                impact: 'Medium',
+                recommendation: 'Add descriptive alt text to every content image.',
+                fixable: true,
+                fixActionType: 'edit-content',
+                relatedEntityIds: [],
+            });
+        }
+    }
+    // -- Duplicate meta titles (cross-entity) --------------------------------
+    const titleGroups = new Map();
+    for (const e of entities) {
+        if (!present(e.metaTitle))
+            continue;
+        const key = normalizeTitle(e.metaTitle);
+        const arr = titleGroups.get(key) ?? [];
+        arr.push(e);
+        titleGroups.set(key, arr);
+    }
+    for (const group of titleGroups.values()) {
+        if (group.length < 2)
+            continue;
+        const ids = group.map((g) => g.entityId).sort();
+        const urls = group.map((g) => g.url).join(', ');
+        issues.push({
+            entityType: group[0].entityType,
+            entityId: group[0].entityId,
+            entityTitle: group[0].title,
+            url: urls,
+            issueKey: issueKeyFor('duplicate-meta-title', ids.join(',')),
+            severity: 'critical',
+            category: 'content',
+            type: 'duplicate-meta-title',
+            title: 'Duplicate meta title detected',
+            description: `Each page must have a unique meta title. ${urls} share the same title.`,
+            impact: 'High',
+            recommendation: 'Differentiate the meta titles so each page targets distinct intent.',
+            fixable: true,
+            fixActionType: 'edit-metadata',
+            relatedEntityIds: ids,
+        });
+    }
+    // -- Broken internal links -----------------------------------------------
+    for (const link of signals.brokenLinks ?? []) {
+        issues.push({
+            entityType: 'page',
+            entityId: link.fromEntityId,
+            entityTitle: link.fromTitle,
+            url: link.fromUrl,
+            issueKey: issueKeyFor('broken-internal-link', `${link.fromEntityId}:${link.url}`),
+            severity: 'critical',
+            category: 'technical',
+            type: 'broken-internal-link',
+            title: 'Internal link returns 404',
+            description: `The link to ${link.url} is broken. Remove or update it to a valid URL.`,
+            impact: 'High',
+            recommendation: 'Fix the link target or create a redirect for the old URL.',
+            fixable: true,
+            fixActionType: 'fix-link',
+            relatedEntityIds: [],
+        });
+    }
+    // -- Slow pages (external perf source) -----------------------------------
+    for (const slow of signals.slowPages ?? []) {
+        issues.push({
+            entityType: 'page',
+            entityId: slow.entityId,
+            entityTitle: slow.title,
+            url: slow.url,
+            issueKey: issueKeyFor('slow-page', slow.entityId),
+            severity: 'warning',
+            category: 'performance',
+            type: 'slow-page',
+            title: 'Page load time exceeds 3 seconds',
+            description: slow.note ?? 'Optimise images, enable lazy loading, and consider a CDN.',
+            impact: 'Medium',
+            recommendation: 'Reduce image sizes and JavaScript; see the technical recommendations.',
+            fixable: false,
+            fixActionType: 'technical-recommendation',
+            relatedEntityIds: [],
+        });
+    }
+    // -- Site score (explainable category sub-scores) ------------------------
+    const total = entities.length;
+    const ratio = (count) => (total === 0 ? 100 : Math.round((count / total) * 100));
+    const withMetaTitle = entities.filter((e) => present(e.metaTitle)).length;
+    const withMetaDesc = entities.filter((e) => present(e.metaDescription)).length;
+    const withH1 = entities.filter((e) => countH1(e.content ?? '') === 1).length;
+    const contentScore = Math.round((ratio(withMetaTitle) + ratio(withMetaDesc) + ratio(withH1)) / 3);
+    const withCanonical = entities.filter((e) => present(e.canonicalUrl)).length;
+    const correctlyIndexed = entities.filter((e) => !(e.shouldBeIndexable !== false && e.noindex === true)).length;
+    const crawlBonus = (signals.sitemapEnabled !== false ? 50 : 0) + (signals.robotsEnabled !== false ? 50 : 0);
+    const technicalScore = Math.round((ratio(withCanonical) + ratio(correctlyIndexed) + crawlBonus) / 3);
+    const brokenCount = (signals.brokenLinks ?? []).length;
+    const chainPenalty = ((signals.redirectChains ?? 0) + (signals.redirectLoops ?? 0)) * 8;
+    const linkRedirectScore = Math.max(0, 100 - brokenCount * 15 - chainPenalty);
+    const withSchema = entities.filter((e) => present(e.structuredDataType)).length;
+    const withOgImage = entities.filter((e) => present(e.ogImage)).length;
+    const structuredSocialScore = Math.round((ratio(withSchema) + ratio(withOgImage)) / 2);
+    const performanceScore = (signals.slowPages ?? []).length > 0
+        ? Math.max(0, 70 - (signals.slowPages ?? []).length * 10)
+        : 70;
+    const siteScore = calculateSiteSeoScore({
+        content: contentScore,
+        technical: technicalScore,
+        linkRedirect: linkRedirectScore,
+        structuredSocial: structuredSocialScore,
+        performance: performanceScore,
+    });
+    // -- Counts + quick wins -------------------------------------------------
+    const counts = {
+        total: issues.length,
+        critical: issues.filter((i) => i.severity === 'critical').length,
+        warning: issues.filter((i) => i.severity === 'warning').length,
+        info: issues.filter((i) => i.severity === 'info').length,
+    };
+    const quickWins = buildQuickWins(issues);
+    return { pages, issues, siteScore, counts, quickWins };
+}
+const IMPACT_RANK = { High: 3, Medium: 2, Low: 1 };
+const SEVERITY_RANK = { critical: 3, warning: 2, info: 1 };
+/**
+ * Derive priority-ranked quick wins by grouping issues by type and ranking by
+ * (impact, severity, count). Never hardcoded — purely a function of detected
+ * issues, so the Overview "Quick Wins" card always reflects reality.
+ */
+export function buildQuickWins(issues) {
+    const byType = new Map();
+    for (const i of issues) {
+        if (!i.fixable)
+            continue;
+        const arr = byType.get(i.type) ?? [];
+        arr.push(i);
+        byType.set(i.type, arr);
+    }
+    const wins = [];
+    for (const [type, group] of byType) {
+        const first = group[0];
+        const count = group.length;
+        wins.push({
+            id: `qw-${type}`,
+            title: quickWinTitle(type, count),
+            explanation: quickWinExplanation(type, count),
+            impact: first.impact === 'High' ? 'High' : first.impact === 'Medium' ? 'Medium' : 'Low',
+            issueType: type,
+            fixActionType: first.fixActionType,
+            count,
+        });
+    }
+    wins.sort((a, b) => {
+        const ai = IMPACT_RANK[a.impact];
+        const bi = IMPACT_RANK[b.impact];
+        if (ai !== bi)
+            return bi - ai;
+        return b.count - a.count;
+    });
+    return wins.slice(0, 5);
+}
+function quickWinTitle(type, count) {
+    switch (type) {
+        case 'missing-meta-description':
+            return `Add meta descriptions to ${count} page${count === 1 ? '' : 's'}`;
+        case 'missing-meta-title':
+            return `Add meta titles to ${count} page${count === 1 ? '' : 's'}`;
+        case 'duplicate-meta-title':
+            return 'Fix duplicate meta title';
+        case 'missing-structured-data':
+            return `Add structured data to ${count} page${count === 1 ? '' : 's'}`;
+        case 'missing-og-image':
+            return `Add Open Graph images to ${count} page${count === 1 ? '' : 's'}`;
+        case 'missing-canonical':
+            return `Add canonical tags to ${count} page${count === 1 ? '' : 's'}`;
+        case 'broken-internal-link':
+            return `Fix ${count} broken internal link${count === 1 ? '' : 's'}`;
+        case 'missing-alt-text':
+            return `Add alt text on ${count} page${count === 1 ? '' : 's'}`;
+        default:
+            return `Resolve ${count} ${type.replace(/-/g, ' ')} issue${count === 1 ? '' : 's'}`;
+    }
+}
+function quickWinExplanation(type, count) {
+    switch (type) {
+        case 'missing-meta-description':
+            return 'Missing meta descriptions reduce click-through rates by up to 30%. This is the single highest-impact fix available.';
+        case 'duplicate-meta-title':
+            return 'Pages sharing the same meta title may be penalised by Google for duplication. Differentiate them.';
+        case 'missing-structured-data':
+            return 'Schema markup enables rich results (star ratings, FAQs, breadcrumbs) and improves visibility.';
+        case 'missing-og-image':
+            return 'Open Graph images significantly improve click-through from social shares.';
+        case 'broken-internal-link':
+            return 'Broken internal links waste crawl budget and frustrate users. Fix or redirect them.';
+        default:
+            return `Resolving ${count} ${type.replace(/-/g, ' ')} issue${count === 1 ? '' : 's'} will improve your SEO health.`;
+    }
+}
+export { gradeForSeoScore };
+//# sourceMappingURL=audit-engine.js.map