@actuate-media/cms-core 0.28.0 → 0.29.0

package/dist/redirects/graph.js

@@ -0,0 +1,136 @@
+/**
+ * Redirect graph utilities — pure functions for chain/loop detection,
+ * loop-prevention on write, path normalization, and stale detection.
+ *
+ * Lives in cms-core (not plugin-redirects) because the API layer needs it and
+ * the dependency direction forbids core importing a plugin. The plugin's
+ * request-time middleware can stay independent.
+ */
+/**
+ * Normalize a path for matching: drop query/hash, ensure a single leading
+ * slash, strip a trailing slash (except root), and lowercase. External
+ * absolute URLs are returned lowercased without a forced leading slash.
+ */
+export function normalizeRedirectPath(input) {
+    if (!input)
+        return '/';
+    let p = String(input).trim();
+    if (/^https?:\/\//i.test(p))
+        return p.toLowerCase();
+    // Strip query + hash.
+    p = p.split('#')[0].split('?')[0];
+    if (!p.startsWith('/'))
+        p = `/${p}`;
+    if (p.length > 1 && p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p.toLowerCase();
+}
+/** True when a redirect points to an external (absolute) destination. */
+export function isExternal(to) {
+    return /^https?:\/\//i.test(to.trim());
+}
+/** Build a normalized from -> edge map of enabled rules. */
+export function buildEdgeMap(rules) {
+    const map = new Map();
+    for (const r of rules) {
+        if (r.enabled === false)
+            continue;
+        const fromNorm = normalizeRedirectPath(r.from);
+        if (map.has(fromNorm))
+            continue; // first rule wins (priority handled upstream)
+        map.set(fromNorm, { to: r.to, toNorm: normalizeRedirectPath(r.to), id: r.id });
+    }
+    return map;
+}
+/**
+ * Follow the redirect map from `start` until a path with no further mapping
+ * (terminal) or a cycle is reached. Bounded by `maxHops`.
+ */
+export function resolveChain(map, start, maxHops = 10) {
+    const startNorm = normalizeRedirectPath(start);
+    const hops = [startNorm];
+    const seen = new Set([startNorm]);
+    let current = startNorm;
+    for (let i = 0; i < maxHops; i++) {
+        const edge = map.get(current);
+        if (!edge) {
+            return { hops, terminal: current, loop: false };
+        }
+        const next = edge.toNorm;
+        hops.push(next);
+        if (seen.has(next)) {
+            return { hops, terminal: next, loop: true };
+        }
+        seen.add(next);
+        current = next;
+    }
+    return { hops, terminal: current, loop: false };
+}
+/**
+ * Detect multi-hop chains (3+ nodes => 2+ redirects) and loops across the
+ * rule set. Returns one entry per chain/loop keyed by a stable id derived from
+ * the starting source.
+ */
+export function detectChainsAndLoops(rules) {
+    const map = buildEdgeMap(rules);
+    const results = [];
+    const reported = new Set();
+    for (const [from] of map) {
+        if (reported.has(from))
+            continue;
+        const res = resolveChain(map, from);
+        if (res.loop) {
+            // Only report loops once per cycle (mark all hops reported).
+            res.hops.forEach((h) => reported.add(h));
+            const breakTo = res.hops.find((h) => h !== from && h !== res.terminal) ?? res.terminal;
+            results.push({
+                id: `loop:${from}`,
+                kind: 'loop',
+                hops: res.hops,
+                suggestedFrom: from,
+                suggestedTo: breakTo,
+            });
+        }
+        else if (res.hops.length >= 3) {
+            // Mark intermediate sources reported so we don't emit sub-chains.
+            res.hops.slice(0, -1).forEach((h) => reported.add(h));
+            results.push({
+                id: `chain:${from}`,
+                kind: 'chain',
+                hops: res.hops,
+                suggestedFrom: from,
+                suggestedTo: res.terminal,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Would adding (or updating to) `from -> to` create a loop or self-redirect?
+ * Simulates the new edge over the existing rule set.
+ */
+export function wouldCreateLoop(rules, from, to, ignoreId) {
+    const fromNorm = normalizeRedirectPath(from);
+    const toNorm = normalizeRedirectPath(to);
+    if (fromNorm === toNorm)
+        return true;
+    if (isExternal(to))
+        return false; // external targets can't loop internally
+    const others = rules.filter((r) => r.id !== ignoreId);
+    const map = buildEdgeMap(others);
+    map.set(fromNorm, { to, toNorm, id: ignoreId ?? '__new__' });
+    const res = resolveChain(map, fromNorm);
+    return res.loop;
+}
+const STALE_DAYS = 60;
+/** A redirect is stale when it hasn't been hit in 60+ days. */
+export function isRedirectStale(lastHitAt, now = new Date()) {
+    if (!lastHitAt)
+        return true;
+    const last = typeof lastHitAt === 'string' ? new Date(lastHitAt) : lastHitAt;
+    if (Number.isNaN(last.getTime()))
+        return true;
+    const ageMs = now.getTime() - last.getTime();
+    return ageMs > STALE_DAYS * 24 * 60 * 60 * 1000;
+}
+//# sourceMappingURL=graph.js.map

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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"}