@actuate-media/cms-core 0.25.0 → 0.26.0

package/dist/content-health/scanner.js

@@ -0,0 +1,263 @@
+/**
+ * Content health scanner — produces the issue rows that power the
+ * dashboard "Content Health" card.
+ *
+ * ## Why a separate module from the cron / endpoint
+ *
+ * The scanner is pure logic — give it a document, get back an array
+ * of issues. The cron drives it across the corpus and persists the
+ * results; the endpoint reads the persisted results. Keeping the
+ * scanner free of I/O dependencies makes it trivially testable
+ * (~10 µs per call, no DB) and lets future callers (CI checks, a
+ * pre-publish hook, etc.) reuse it without dragging in cron
+ * infrastructure.
+ *
+ * ## Why HEAD probes for the link checker
+ *
+ * Internal links 404 in two flavors: a hard 404 from the framework
+ * (page genuinely doesn't exist) and a soft 404 where the framework
+ * returns 200 with a "not found" template. We only catch the first.
+ * That's fine — the dashboard's job is to surface the high-confidence
+ * issues, not chase ambiguous soft-404 heuristics. The scanner can
+ * be extended with response-body matching later if the editor
+ * feedback warrants it.
+ *
+ * ## Why we count alt-less images per document, not per image
+ *
+ * The dashboard surfaces total issue counts. Storing one row per
+ * image would blow up the issue table for pages with 20+
+ * unannotated photos and provide no extra value (the editor still
+ * gets a single "12 images need alt text" row in the UI). We
+ * collapse to one row per (document, type) with `count` carrying
+ * the per-document magnitude.
+ */
+// ─── Helpers ───────────────────────────────────────────────────────────────
+/**
+ * Return the longest plausible HTML payload from a document. CMS
+ * collections use different field names (`body`, `content`,
+ * `richText`, `html`) so we try each and pick the longest — that
+ * resolves the common case where a document has both a plain
+ * `excerpt` and a rich `body`, and we want to scan the body.
+ */
+function extractHtml(data) {
+    const candidates = ['body', 'content', 'richText', 'richtext', 'html', 'description'];
+    let best = '';
+    for (const key of candidates) {
+        const v = data[key];
+        if (typeof v === 'string' && v.length > best.length)
+            best = v;
+    }
+    return best;
+}
+const META_DESCRIPTION_KEYS = ['metaDescription', 'seoDescription', 'meta_description'];
+function getMetaDescription(data) {
+    for (const key of META_DESCRIPTION_KEYS) {
+        const v = data[key];
+        if (typeof v === 'string' && v.trim().length > 0)
+            return v.trim();
+    }
+    // Nested SEO objects (e.g. data.seo.description).
+    const seo = data['seo'];
+    if (seo && typeof seo === 'object') {
+        const obj = seo;
+        const v = obj['description'] ?? obj['metaDescription'];
+        if (typeof v === 'string' && v.trim().length > 0)
+            return v.trim();
+    }
+    return null;
+}
+/**
+ * Count <img> tags in the HTML that don't carry an `alt` attribute.
+ * Matches the existing a11y rule in `a11y/index.ts` so the scanner
+ * agrees with the per-document audit panel.
+ */
+export function countMissingAltImages(html) {
+    if (!html)
+        return 0;
+    const re = /<img(?![^>]*\salt\s*=)[^>]*>/gi;
+    let count = 0;
+    // We don't iterate matches into an array — just count, so memory
+    // stays bounded even on huge pages.
+    while (re.exec(html) !== null)
+        count++;
+    return count;
+}
+/**
+ * Extract candidate URLs from <a href="..."> attributes. Returns
+ * the raw href values; classification (internal vs external,
+ * absolute vs relative) happens in the caller.
+ */
+export function extractLinks(html) {
+    if (!html)
+        return [];
+    const out = [];
+    const re = /<a\b[^>]*\shref\s*=\s*("([^"]*)"|'([^']*)')/gi;
+    let match;
+    while ((match = re.exec(html)) !== null) {
+        const url = (match[2] ?? match[3] ?? '').trim();
+        if (url.length > 0)
+            out.push(url);
+    }
+    return out;
+}
+/**
+ * Decide whether a URL is "internal" relative to `siteOrigin`.
+ * Internal links include:
+ *   - relative paths: `/about`, `./page`, `../foo`
+ *   - same-origin absolute URLs: `https://example.com/page`
+ *
+ * Excluded:
+ *   - external URLs (different origin)
+ *   - hash-only anchors (`#section`)
+ *   - non-http schemes (`mailto:`, `tel:`, `javascript:`, etc.)
+ *   - protocol-relative URLs to a different host (`//other.com/x`)
+ */
+export function classifyLink(url, siteOrigin) {
+    const trimmed = url.trim();
+    if (trimmed.length === 0)
+        return { isInternal: false, resolved: null };
+    if (trimmed.startsWith('#'))
+        return { isInternal: false, resolved: null };
+    // Reject non-http schemes outright.
+    const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+    if (schemeMatch) {
+        const scheme = schemeMatch[1].toLowerCase();
+        if (scheme !== 'http' && scheme !== 'https')
+            return { isInternal: false, resolved: null };
+    }
+    let parsedOrigin;
+    try {
+        parsedOrigin = new URL(siteOrigin);
+    }
+    catch {
+        return { isInternal: false, resolved: null };
+    }
+    try {
+        const resolved = new URL(trimmed, parsedOrigin);
+        if (resolved.protocol !== 'http:' && resolved.protocol !== 'https:') {
+            return { isInternal: false, resolved: null };
+        }
+        return {
+            isInternal: resolved.origin === parsedOrigin.origin,
+            resolved: resolved.toString(),
+        };
+    }
+    catch {
+        return { isInternal: false, resolved: null };
+    }
+}
+/**
+ * Single-link reachability probe. Default implementation used by
+ * the cron — issues a HEAD with a 5s timeout, falls back to GET if
+ * HEAD returns 405/501 (some frameworks reject HEAD).
+ */
+export async function checkInternalLinkReachable(url, timeoutMs = 5000) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const head = await fetch(url, {
+            method: 'HEAD',
+            redirect: 'follow',
+            signal: controller.signal,
+        });
+        if (head.status === 405 || head.status === 501) {
+            // Method not allowed / not implemented → retry with GET.
+            const get = await fetch(url, {
+                method: 'GET',
+                redirect: 'follow',
+                signal: controller.signal,
+            });
+            return get.status < 400;
+        }
+        return head.status < 400;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+// ─── Scanner ───────────────────────────────────────────────────────────────
+/**
+ * Run all checks on a single document. The link checker is
+ * concurrency-bounded to `LINK_CHECK_CONCURRENCY` per document so a
+ * page with 200 links doesn't open 200 sockets at once.
+ *
+ * Each issue type appears at most once in the returned array. The
+ * shape `{ type, count, details }` lets the caller upsert by
+ * `(documentId, type)` and rely on `count` for the magnitude
+ * surfaced in the dashboard.
+ */
+export async function scanDocument(doc, opts = {}) {
+    const outdatedDays = opts.outdatedDays ?? 90;
+    const issues = [];
+    // 1. Missing meta description --------------------------------------------
+    if (!getMetaDescription(doc.data)) {
+        issues.push({ type: 'MISSING_META_DESCRIPTION', count: 1 });
+    }
+    // 2. Missing alt text ----------------------------------------------------
+    const html = extractHtml(doc.data);
+    const altLessImages = countMissingAltImages(html);
+    if (altLessImages > 0) {
+        issues.push({ type: 'MISSING_ALT_TEXT', count: altLessImages });
+    }
+    // 3. Outdated content ----------------------------------------------------
+    const referenceTime = doc.publishedAt ?? doc.updatedAt;
+    const ageMs = Date.now() - referenceTime.getTime();
+    if (ageMs > outdatedDays * 24 * 60 * 60 * 1000) {
+        issues.push({
+            type: 'OUTDATED_CONTENT',
+            count: 1,
+            details: {
+                ageDays: Math.floor(ageMs / (24 * 60 * 60 * 1000)),
+                threshold: outdatedDays,
+            },
+        });
+    }
+    // 4. Broken internal links ----------------------------------------------
+    if (opts.checkLink && opts.siteOrigin) {
+        const links = extractLinks(html);
+        const internalUrls = new Set();
+        for (const raw of links) {
+            const { isInternal, resolved } = classifyLink(raw, opts.siteOrigin);
+            if (isInternal && resolved)
+                internalUrls.add(resolved);
+        }
+        const broken = [];
+        if (internalUrls.size > 0) {
+            const checker = opts.checkLink;
+            await Promise.all(chunk([...internalUrls], LINK_CHECK_CONCURRENCY).map(async (group) => {
+                const results = await Promise.all(group.map((u) => checker(u).catch(() => false)));
+                group.forEach((u, i) => {
+                    if (!results[i])
+                        broken.push(u);
+                });
+            }));
+        }
+        if (broken.length > 0) {
+            issues.push({
+                type: 'BROKEN_INTERNAL_LINK',
+                count: broken.length,
+                details: { urls: broken.slice(0, 10) }, // cap stored details
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Concurrency cap for the per-document link checker. Vercel
+ * functions are wall-time bounded; opening 5 concurrent sockets
+ * keeps us under the typical 60s soft cap even for pages with
+ * 100+ internal links.
+ */
+const LINK_CHECK_CONCURRENCY = 5;
+function chunk(arr, size) {
+    if (size <= 0)
+        return [arr];
+    const out = [];
+    for (let i = 0; i < arr.length; i += size)
+        out.push(arr.slice(i, i + size));
+    return out;
+}
+//# sourceMappingURL=scanner.js.map

package/dist/content-health/scanner.js.map

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

package/dist/diagnostics/api-metrics.d.ts

@@ -0,0 +1,135 @@
+/**
+ * API request instrumentation that powers the Dashboard "Delivery API"
+ * tiles (request volume / error rate / avg latency / p95).
+ *
+ * ## Why per-minute aggregated buckets and not per-request rows
+ *
+ * A single 24-hour window at 100 req/s on 20 routes is ~17M raw rows,
+ * but the same window aggregated to (minute × route × status-bucket)
+ * is ≤ 1440 × 20 × 5 = 144k rows — and in practice far less because
+ * most route/minute combinations have zero traffic. The reader
+ * (`/stats/api-delivery`) folds the last 1440 minute buckets into
+ * four scalars; the writer does one atomic UPSERT per request via
+ * raw SQL.
+ *
+ * ## Why p95 via histogram and not from raw samples
+ *
+ * Storing a histogram per bucket gives us percentile estimates with
+ * ~10% error vs ground truth while keeping the table tiny. The
+ * `LATENCY_BUCKETS` boundary list is log-scale (powers of 2 in
+ * milliseconds) so it covers ~1 ms heartbeats through multi-second
+ * outliers in 12 columns. p95 falls out as a `findIndex` once the
+ * histogram is merged across all minute buckets in the window.
+ *
+ * ## Why fire-and-forget and not awaited
+ *
+ * Metric recording MUST NOT slow the user-facing response. The
+ * `record()` call dispatches the UPSERT to a `void`-discarded promise
+ * so a slow DB round-trip never blocks the request that produced
+ * the metric. Errors are swallowed at the source — losing a metric
+ * sample is strictly preferable to surfacing a metric-pipeline error
+ * to the user.
+ *
+ * ## Why we self-exempt the dashboard polling routes
+ *
+ * The dashboard refetches `/stats` and `/stats/api-delivery` on a
+ * timer. If we counted those requests they'd dominate the volume
+ * tile and inflate the error rate (a logged-out tab would hit
+ * `/stats` and get 401 repeatedly). The route-normaliser excludes
+ * them explicitly — see `shouldRecord`.
+ */
+/**
+ * Upper bound (exclusive) of each histogram bucket, in milliseconds.
+ * The last bucket is `>= 1024 ms` (no upper bound).
+ *
+ * Indexed:
+ *   0: <1ms     1: 1-2ms     2: 2-4ms     3: 4-8ms
+ *   4: 8-16ms   5: 16-32ms   6: 32-64ms   7: 64-128ms
+ *   8: 128-256  9: 256-512  10: 512-1024 11: >=1024
+ */
+export declare const LATENCY_BUCKETS: readonly [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024];
+export declare const HISTOGRAM_LENGTH: number;
+export type StatusBucket = '2xx' | '3xx' | '4xx' | '5xx' | 'other';
+export interface ApiMetricSample {
+    /** Request path, CMS-relative — e.g. `/collections/posts/abc123`. */
+    pathname: string;
+    status: number;
+    /** Response time in milliseconds. May be a float. */
+    durationMs: number;
+}
+/**
+ * Bucket a status code into one of 5 families. We keep the 1xx family
+ * out of the public type because no CMS route ever responds with one;
+ * if it ever happens, the `other` bucket catches it instead of
+ * silently being lost.
+ */
+export declare function statusBucketOf(status: number): StatusBucket;
+/**
+ * Return the index (0..HISTOGRAM_LENGTH-1) of the histogram bucket
+ * that this latency falls into. NaN / negative values fall in bucket
+ * 0 (treated as "<1ms") so a metric write never crashes on a bad
+ * input.
+ */
+export declare function histogramBucketIndex(durationMs: number): number;
+/**
+ * Build a fresh histogram array with a single sample placed in the
+ * correct bucket. Used to produce the JSON payload for an INSERT.
+ */
+export declare function makeHistogramFor(durationMs: number): number[];
+/**
+ * Element-wise add two histograms. Tolerant of either operand being
+ * missing or shorter than `HISTOGRAM_LENGTH` — defends against schema
+ * mismatches (e.g. an old row written before a bucket boundary change).
+ */
+export declare function mergeHistograms(a: number[] | null | undefined, b: number[]): number[];
+/**
+ * Snap a Date to the start of its UTC minute. Returns a new Date —
+ * never mutates the input.
+ */
+export declare function bucketStartFor(now?: Date | number): Date;
+/**
+ * Estimate percentile-N from a merged histogram. Returns the upper
+ * bound of the bucket that contains the requested percentile —
+ * which is the right "user-visible" answer (we are happy to say
+ * "p95 < 256ms" rather than guess the exact value inside the
+ * 128-256 bucket).
+ *
+ * For the overflow bucket (no upper bound), we report
+ * `LATENCY_BUCKETS[last]` as a lower-bound estimate; callers
+ * displaying this should annotate with a "≥" prefix if they want
+ * to expose the open-ended nature.
+ */
+export declare function estimatePercentile(histogram: number[], percentile: number): number;
+/**
+ * Normalise a request path to bound metric-row cardinality.
+ *
+ *   /collections/posts/abc123        →  /collections/posts/:id
+ *   /globals/site-settings           →  /globals/:slug
+ *   /collections/posts/abc123/restore→  /collections/posts/:id/restore
+ *   /unknown/long/path/that/leaks    →  /other
+ *
+ * The "/other" bucket catches anything we don't explicitly know
+ * about so a single hostile client with random URLs can't blow up
+ * the table.
+ */
+export declare function normalizeRoute(pathname: string): string;
+/**
+ * Routes that the dashboard polls itself, plus webhooks the cron
+ * fires. Counting these would either (a) cause feedback loops
+ * inflating the volume tile or (b) report cron-only traffic the
+ * editor never produces. The instrumentation skips them.
+ */
+export declare function shouldRecord(normalizedRoute: string): boolean;
+/**
+ * Record one API request to the metrics table. **Fire-and-forget** —
+ * callers MUST NOT `await` this. Errors are swallowed; the next
+ * request retries, and 1-minute aggregates are robust to occasional
+ * write loss.
+ *
+ * Writes a single SQL UPSERT so two concurrent requests landing in
+ * the same bucket interleave cleanly via Postgres's MVCC + the
+ * unique-on-conflict path. The histogram column is merged
+ * element-wise inside SQL, so we never read-modify-write from JS.
+ */
+export declare function recordApiRequest(sample: ApiMetricSample): void;
+//# sourceMappingURL=api-metrics.d.ts.map

package/dist/diagnostics/api-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-metrics.d.ts","sourceRoot":"","sources":["../../src/diagnostics/api-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AASH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,wDAAyD,CAAA;AAErF,eAAO,MAAM,gBAAgB,QAA6B,CAAA;AAE1D,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAAA;AAElE,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;CACnB;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAM3D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAI7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAMrF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,IAAI,GAAG,MAAmB,GAAG,IAAI,CAGpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAalF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiBvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAE7D;AAiGD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAY9D"}