@pseolint/core 0.3.1 → 0.4.0

package/dist/fetch-observer.js

@@ -0,0 +1,124 @@
+/**
+ * Fetch observation + origin-readiness aggregation.
+ *
+ * Every HTTP request during an audit emits a `FetchObservation` (url, status,
+ * wall-clock duration, whether the cache served or revalidated it). These
+ * observations feed two consumers:
+ *
+ *   1. `computeReadiness` — post-crawl aggregate (median / p95 / 5xx count /
+ *      cache-assist ratio) surfaced as the `audit/origin-readiness` finding.
+ *   2. `BackpressureMonitor` (backpressure.ts) — in-flight watchdog that aborts
+ *      the audit if the origin degrades under concurrent load.
+ *
+ * Both consumers treat pure cache hits (`fromCache` with no revalidation)
+ * as non-informative about the origin — latency stats should describe the
+ * SERVER, not our local SSD.
+ */
+/** v0.4: detect dev-server framework from response headers. Returns null when not a known dev server. */
+export function detectDevServer(headers) {
+    const lower = {};
+    for (const [k, v] of Object.entries(headers))
+        lower[k.toLowerCase()] = v;
+    const xpb = lower["x-powered-by"] ?? "";
+    if (xpb.toLowerCase().includes("next"))
+        return "nextjs";
+    // x-nextjs-* headers (next/server runtime) and __nextjs_* cookies.
+    const cookie = lower["set-cookie"] ?? lower["cookie"] ?? "";
+    if (Object.keys(lower).some((k) => k.startsWith("x-nextjs-")) || /__nextjs_/i.test(cookie)) {
+        return "nextjs";
+    }
+    if (Object.keys(lower).some((k) => k.startsWith("x-vite-")))
+        return "vite";
+    if (Object.keys(lower).some((k) => k.startsWith("x-astro-")))
+        return "astro";
+    return null;
+}
+function percentile(sortedAsc, p) {
+    if (sortedAsc.length === 0)
+        return 0;
+    if (sortedAsc.length === 1)
+        return sortedAsc[0];
+    // Nearest-rank method (simple, deterministic for small samples).
+    const rank = Math.ceil((p / 100) * sortedAsc.length) - 1;
+    return sortedAsc[Math.max(0, Math.min(sortedAsc.length - 1, rank))];
+}
+/**
+ * Aggregate a run's fetch observations into a readiness report. Returns `null`
+ * when there's no origin data to speak to (zero fetches, or all pure cache
+ * hits). Null is a signal to callers that the finding should be suppressed —
+ * it's not a result worth displaying.
+ */
+export function computeReadiness(observations, thresholds = {}) {
+    const framework = thresholds.detectedFramework ?? null;
+    // Dev servers (Next/Vite/Astro) routinely take seconds on cold compile.
+    // Spec §4.7: cap p95 at 10s and skip the first 5 fetches as warmup grace.
+    const isDevFramework = framework !== null;
+    const defaultNotReady = isDevFramework ? 10000 : 3000;
+    const defaultConcerning = isDevFramework ? 3000 : 800;
+    const t = {
+        notReadyP95Ms: thresholds.notReadyP95Ms ?? defaultNotReady,
+        concerningP95Ms: thresholds.concerningP95Ms ?? defaultConcerning,
+        notReadyErrorRatio: thresholds.notReadyErrorRatio ?? 0.1,
+    };
+    // Live fetches = anything that actually spoke to the origin (revalidation
+    // counts because the 304 round-trip is a real network call).
+    const live = observations.filter((o) => !o.fromCache || o.revalidated);
+    if (live.length === 0)
+        return null;
+    // Warmup grace: drop the first 5 live fetches from latency percentiles when
+    // a dev-server framework was detected. Keep them in the success/error ratios
+    // so genuine 5xx during warmup still surface.
+    const liveForLatency = isDevFramework && live.length > 5
+        ? live.slice(5)
+        : live;
+    const durations = liveForLatency.map((o) => o.durationMs).sort((a, b) => a - b);
+    const medianMs = durations.length > 0 ? percentile(durations, 50) : 0;
+    const p95Ms = durations.length > 0 ? percentile(durations, 95) : 0;
+    const serverErrorCount = live.filter((o) => o.status >= 500 && o.status < 600).length;
+    const successCount = live.filter((o) => o.status >= 200 && o.status < 400).length;
+    const serverErrorRatio = serverErrorCount / live.length;
+    const successRatio = successCount / live.length;
+    const cacheAssistCount = observations.filter((o) => o.fromCache || o.revalidated).length;
+    const cacheAssistRatio = observations.length === 0 ? 0 : cacheAssistCount / observations.length;
+    let verdict;
+    if (p95Ms >= t.notReadyP95Ms || serverErrorRatio >= t.notReadyErrorRatio) {
+        verdict = "not-ready";
+    }
+    else if (p95Ms >= t.concerningP95Ms) {
+        verdict = "concerning";
+    }
+    else {
+        verdict = "ready";
+    }
+    return {
+        liveFetchCount: live.length,
+        medianMs,
+        p95Ms,
+        successRatio,
+        serverErrorCount,
+        serverErrorRatio,
+        cacheAssistRatio,
+        verdict,
+        ...(framework ? { detectedFramework: framework } : {}),
+    };
+}
+/**
+ * A small collector so callers can hand the same object to the fetch pipeline
+ * (as an onObservation callback) and to the readiness/backpressure consumers.
+ */
+export class FetchObserver {
+    entries = [];
+    record(obs) {
+        this.entries.push(obs);
+    }
+    getAll() {
+        return this.entries;
+    }
+    snapshotLast(n) {
+        return this.entries.slice(Math.max(0, this.entries.length - n));
+    }
+    get size() {
+        return this.entries.length;
+    }
+}
+//# sourceMappingURL=fetch-observer.js.map

package/dist/fetch-observer.js.map

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

package/dist/formatters/console.d.ts

@@ -1,15 +1,13 @@
 import type { AuditSummary } from "../types.js";
-/**
- * AEO-specific score label. AEO score is raw "damage" 0–100 — low is good.
- *   0–20  AI-Ready    pages structured for citation
- *  21–40  Partial     some citable, others vulnerable
- *  41–60  Vulnerable  most pages will be summarized away
- *  61–80  Invisible   pages offer nothing AI can't synthesize itself
- *  81–100 Ghost       actively blocked + no citable structure
- */
-export declare function aeoScoreLabel(score: number): string;
 export interface ConsoleFormatOptions {
     noColor?: boolean;
+    /** When true, list every finding bucketed by severity instead of just top fixes. */
+    verbose?: boolean;
 }
 export declare function formatConsole(summary: AuditSummary, options?: ConsoleFormatOptions): string;
+/**
+ * Legacy helper retained for back-compat with existing tests/imports.
+ * AEO score band → human label. Low score = AI-Ready, high = Ghost.
+ */
+export declare function aeoScoreLabel(score: number): string;
 //# sourceMappingURL=console.d.ts.map

package/dist/formatters/console.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/formatters/console.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAmD,MAAM,aAAa,CAAC;AA4BjG;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD;AAuED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAwP3F"}
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/formatters/console.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAOb,MAAM,aAAa,CAAC;AAgHrB,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAqID,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CA8E3F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD"}