@gscdump/analysis 3.8.0 → 4.0.1

package/dist/report/reports/movers.mjs

@@ -1,5 +1,5 @@
 import { requireComparisonWindow } from "../require.mjs";
-import { reportRows, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
+import { reportRows, resultTotal, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
 import { defineReport } from "@gscdump/engine/report";
 const DEFAULT_MAX = 5;
 const DEFAULT_MIN_CHANGE = 5;
@@ -32,15 +32,28 @@ const moversReport = defineReport({
 		};
 		return [
 			{
-				key: "movers",
+				key: "movers-rising",
 				type: "movers",
 				params: {
 					...cur,
 					...prev,
+					direction: "rising",
 					limit: 200
 				},
 				required: true,
-				feeds: ["rising", "decliners"]
+				feeds: ["rising"]
+			},
+			{
+				key: "movers-declining",
+				type: "movers",
+				params: {
+					...cur,
+					...prev,
+					direction: "declining",
+					limit: 200
+				},
+				required: true,
+				feeds: ["decliners"]
 			},
 			{
 				key: "decay",
@@ -67,18 +80,19 @@ const moversReport = defineReport({
 		const max = ctx.params.maxFindings ?? DEFAULT_MAX;
 		const minChange = ctx.params.minClicksChange ?? DEFAULT_MIN_CHANGE;
 		const sections = [];
-		const moversRes = results.movers;
+		const risingRes = results["movers-rising"];
+		const decliningRes = results["movers-declining"];
 		const decayRes = results.decay;
 		const strikingRes = results.striking;
-		sections.push(buildMoversSection(moversRes, "rising", max, minChange));
-		sections.push(buildDeclinersSection(moversRes, decayRes, max, minChange));
+		sections.push(buildMoversSection(risingRes, "rising", max, minChange));
+		sections.push(buildDeclinersSection(decliningRes, decayRes, max, minChange));
 		sections.push(buildStrikingSection(strikingRes, max));
 		return { sections };
 	}
 });
 function buildMoversSection(res, direction, max, minChange) {
 	const rows = reportRows(res).filter((r) => r.direction === direction && Math.abs(r.clicksChange) >= minChange).sort((a, b) => Math.abs(b.clicksChange) - Math.abs(a.clicksChange));
-	const total = rows.length;
+	const total = resultTotal(res, rows.length);
 	const kept = rows.slice(0, max);
 	const findings = kept.map((r) => ({
 		entity: {
@@ -115,7 +129,8 @@ function buildMoversSection(res, direction, max, minChange) {
 	};
 }
 function buildDeclinersSection(moversRes, decayRes, max, minChange) {
-	const decliningQueries = reportRows(moversRes).filter((r) => r.direction === "declining" && Math.abs(r.clicksChange) >= minChange).slice(0, max);
+	const decliningRows = reportRows(moversRes).filter((r) => r.direction === "declining" && Math.abs(r.clicksChange) >= minChange).sort((a, b) => Math.abs(b.clicksChange) - Math.abs(a.clicksChange));
+	const decliningQueries = decliningRows.slice(0, max);
 	const lostPages = reportRows(decayRes).sort((a, b) => b.lostClicks - a.lostClicks).slice(0, max);
 	const findings = [...decliningQueries.map((r) => ({
 		entity: {
@@ -161,12 +176,14 @@ function buildDeclinersSection(moversRes, decayRes, max, minChange) {
 			magnitudeLabel: `${Math.round(totalLost)} clicks lost`
 		},
 		findings,
-		coverage: decayRes && moversRes ? "full" : "partial"
+		truncated: truncation(resultTotal(moversRes, decliningRows.length), decliningQueries.length),
+		coverage: sectionCoverage(moversRes) === "full" && sectionCoverage(decayRes) === "full" ? "full" : "partial"
 	};
 }
 function buildStrikingSection(res, max) {
 	const rows = reportRows(res).sort((a, b) => b.potentialClicks - a.potentialClicks);
 	const kept = rows.slice(0, max);
+	const total = resultTotal(res, rows.length);
 	const findings = kept.map((r) => ({
 		entity: {
 			kind: "query",
@@ -186,7 +203,7 @@ function buildStrikingSection(res, max) {
 		severity: "low",
 		summary: { magnitudeLabel: `${kept.reduce((s, r) => s + r.potentialClicks, 0)} potential clicks` },
 		findings,
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(total, kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "striking-distance")
 	};

package/dist/report/reports/opportunities.mjs

@@ -1,4 +1,4 @@
-import { reportRows, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
+import { reportRows, resultTotal, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
 import { defineReport } from "@gscdump/engine/report";
 const DEFAULT_MAX = 5;
 const opportunitiesReport = defineReport({
@@ -87,7 +87,7 @@ function buildStrikingSection(res, max) {
 		severity: "low",
 		summary: { magnitudeLabel: `${Math.round(totalPotential)} potential clicks` },
 		findings,
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "striking-distance")
 	};
@@ -114,11 +114,14 @@ function buildOpportunitySection(res, max) {
 			},
 			why: r.page ? `low CTR on ${r.page}` : "low CTR vs position"
 		})),
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "opportunity")
 	};
 }
+function zeroClickWhy(r) {
+	return `${`${(r.ctr * 100).toFixed(1)}% CTR`} at position ${r.position.toFixed(1)} on ${r.page}`;
+}
 function buildZeroClickSection(res, max) {
 	const rows = reportRows(res).sort((a, b) => b.impressions - a.impressions);
 	const kept = rows.slice(0, max);
@@ -129,18 +132,19 @@ function buildZeroClickSection(res, max) {
 		},
 		metrics: {
 			impressions: r.impressions,
+			clicks: r.clicks,
 			position: r.position,
 			ctr: r.ctr
 		},
-		why: `0 clicks on ${r.page}`
+		why: zeroClickWhy(r)
 	}));
 	return {
 		id: "zero-click",
 		title: "Zero-click queries",
 		severity: "info",
-		summary: { magnitudeLabel: `${kept.reduce((s, r) => s + r.impressions, 0)} impressions wasted` },
+		summary: { magnitudeLabel: `${kept.reduce((s, r) => s + r.impressions, 0)} impressions at low CTR` },
 		findings,
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "zero-click")
 	};
@@ -164,7 +168,7 @@ function buildMigrationSection(res, max) {
 			},
 			why: `migrating from ${r.sourcePage}`
 		})),
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "query-migration")
 	};

package/dist/report/reports/pre-publish.mjs

@@ -2,6 +2,7 @@ import { requireReportParam } from "../require.mjs";
 import { reportRows, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
 import { defineReport } from "@gscdump/engine/report";
 const DEFAULT_MAX = 10;
+const FULL_OUTPUT = 5e4;
 const prePublishReport = defineReport({
 	id: "pre-publish",
 	description: "Pre-publish guard: cannibalization risk and striking-distance peers for a candidate topic or URL.",
@@ -30,7 +31,7 @@ const prePublishReport = defineReport({
 			type: "cannibalization",
 			params: {
 				...dates,
-				limit: 200
+				limit: FULL_OUTPUT
 			},
 			feeds: ["cannibalization-risk"]
 		}, {
@@ -38,7 +39,7 @@ const prePublishReport = defineReport({
 			type: "striking-distance",
 			params: {
 				...dates,
-				limit: 200
+				limit: FULL_OUTPUT
 			},
 			feeds: ["striking-peers"]
 		}];

package/dist/report/reports/risks.mjs

@@ -1,5 +1,5 @@
 import { requireComparisonWindow } from "../require.mjs";
-import { reportRows, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
+import { reportRows, resultTotal, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
 import { defineReport } from "@gscdump/engine/report";
 const DEFAULT_MAX = 5;
 const risksReport = defineReport({
@@ -100,7 +100,7 @@ function buildDecaySection(res, max) {
 			magnitudeLabel: `${Math.round(totalLost)} clicks lost`
 		},
 		findings,
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "decay")
 	};
@@ -129,7 +129,7 @@ function buildCannibalizationSection(res, max) {
 		severity: kept.length ? "medium" : "info",
 		summary: {},
 		findings,
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "cannibalization")
 	};
@@ -155,7 +155,7 @@ function buildDarkTrafficSection(res, max) {
 		severity: kept.length ? "low" : "info",
 		summary: { magnitudeLabel: `${Math.round(totalDark)} unattributed clicks` },
 		findings,
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "dark-traffic")
 	};
@@ -181,7 +181,7 @@ function buildDeviceGapSection(res, max) {
 			},
 			why: `desktop vs mobile delta`
 		})),
-		truncated: truncation(rows.length, kept.length),
+		truncated: truncation(resultTotal(res, rows.length), kept.length),
 		coverage: sectionCoverage(res),
 		artifact: sectionArtifact(res, "device-gap")
 	};

package/dist/report/runtime.mjs

@@ -2,16 +2,18 @@ import { analysisErrorToException, analysisErrors } from "../errors.mjs";
 import { runAnalyzerFromSource } from "@gscdump/engine/analyzer";
 import { err, ok, unwrapResult } from "gscdump/result";
 import { computeInputHash } from "@gscdump/engine/report";
-async function executeStep(source, analyzers, step) {
+async function executeStep(source, analyzers, step, fetchBudget) {
 	const params = {
 		...step.params,
+		...fetchBudget != null ? { fetchBudget } : {},
 		type: step.type
 	};
 	return runAnalyzerFromSource(source, params, analyzers).then((result) => ({
 		state: {
 			key: step.key,
 			type: step.type,
-			status: "done"
+			status: "done",
+			...result.meta.coverage ? { coverage: result.meta.coverage } : {}
 		},
 		result
 	})).catch((thrown) => {
@@ -63,7 +65,7 @@ async function runReportResult(report, opts) {
 		registryVersion: opts.ctx.registryVersion
 	});
 	const steps = report.plan(opts.ctx.params, opts.ctx.window);
-	const outcomes = await Promise.all(steps.map((s) => executeStep(opts.source, opts.analyzers, s)));
+	const outcomes = await Promise.all(steps.map((s) => executeStep(opts.source, opts.analyzers, s, opts.ctx.fetchBudget)));
 	const required = new Map(steps.filter((s) => s.required).map((s) => [s.key, s]));
 	const errored = outcomes.filter((o) => o.state.status === "error");
 	for (const o of errored) if (required.has(o.state.key)) return err(analysisErrors.requiredStepFailed(report.id, o.state.key, o.state.error ?? "unknown error", o.cause));

package/dist/report/sections.mjs

@@ -2,7 +2,11 @@ function reportRows(result) {
 	return result?.results ?? [];
 }
 function sectionCoverage(result) {
-	return result ? "full" : "partial";
+	return result && result.meta.coverage?.kind !== "truncated" ? "full" : "partial";
+}
+function resultTotal(result, fallback) {
+	const total = result?.meta.total;
+	return typeof total === "number" ? Math.max(total, fallback) : fallback;
 }
 function sectionArtifact(result, analyzer, params = {}) {
 	return result ? {
@@ -19,4 +23,4 @@ function truncation(total, kept) {
 		total
 	} : void 0;
 }
-export { reportRows, sectionArtifact, sectionCoverage, truncation };
+export { reportRows, resultTotal, sectionArtifact, sectionCoverage, truncation };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/analysis",
   "type": "module",
-  "version": "3.8.0",
+  "version": "4.0.1",
   "description": "GSC analyzers — striking-distance, opportunity, movers, decay, brand, clustering, concentration, seasonality. Pure row-based + DuckDB-native.",
   "author": {
     "name": "Harlan Wilton",
@@ -58,16 +58,16 @@
     "dist"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13.0"
   },
   "dependencies": {
-    "@gscdump/engine": "^3.8.0",
-    "@gscdump/engine-gsc-api": "^3.8.0",
-    "gscdump": "^3.8.0",
+    "@gscdump/engine": "^4.0.1",
+    "@gscdump/engine-gsc-api": "^4.0.1",
+    "gscdump": "^4.0.1",
     "pluralize": "^8.0.0"
   },
   "devDependencies": {
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "build": "obuild",