@gscdump/analysis 1.4.0 → 1.4.1

package/dist/report/reports/opportunities.mjs

@@ -0,0 +1,184 @@
+import { reportRows, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
+import { defineReport } from "@gscdump/engine/report";
+const DEFAULT_MAX = 5;
+const opportunitiesReport = defineReport({
+	id: "opportunities",
+	description: "Striking-distance, low-CTR, zero-click, and query-migration opportunities.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "none",
+	argsSpec: { "max-findings": {
+		type: "number",
+		description: "Cap findings per section",
+		default: DEFAULT_MAX
+	} },
+	plan: (_params, window) => {
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [
+			{
+				key: "striking",
+				type: "striking-distance",
+				params: {
+					...dates,
+					limit: 100
+				},
+				required: true
+			},
+			{
+				key: "opportunity",
+				type: "opportunity",
+				params: {
+					...dates,
+					limit: 100
+				}
+			},
+			{
+				key: "zero-click",
+				type: "zero-click",
+				params: {
+					...dates,
+					limit: 100
+				}
+			},
+			{
+				key: "query-migration",
+				type: "query-migration",
+				params: {
+					...dates,
+					limit: 50
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX;
+		return { sections: [
+			buildStrikingSection(results.striking, max),
+			buildOpportunitySection(results.opportunity, max),
+			buildZeroClickSection(results["zero-click"], max),
+			buildMigrationSection(results["query-migration"], max)
+		] };
+	}
+});
+function buildStrikingSection(res, max) {
+	const rows = reportRows(res).sort((a, b) => b.potentialClicks - a.potentialClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			position: r.position,
+			impressions: r.impressions,
+			clicks: r.clicks,
+			potentialClicks: r.potentialClicks
+		},
+		why: r.page ? `on ${r.page}` : void 0
+	}));
+	const totalPotential = kept.reduce((s, r) => s + r.potentialClicks, 0);
+	return {
+		id: "striking-distance",
+		title: "Striking distance",
+		severity: "low",
+		summary: { magnitudeLabel: `${Math.round(totalPotential)} potential clicks` },
+		findings,
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: [],
+		artifact: sectionArtifact(res, "striking-distance")
+	};
+}
+function buildOpportunitySection(res, max) {
+	const rows = reportRows(res).sort((a, b) => b.opportunityScore - a.opportunityScore);
+	const kept = rows.slice(0, max);
+	return {
+		id: "low-ctr",
+		title: "Underperforming CTR",
+		severity: "low",
+		summary: {},
+		findings: kept.map((r) => ({
+			entity: {
+				kind: "query",
+				value: r.keyword
+			},
+			metrics: {
+				opportunityScore: r.opportunityScore,
+				ctr: r.ctr,
+				position: r.position,
+				impressions: r.impressions,
+				potentialClicks: r.potentialClicks
+			},
+			why: r.page ? `low CTR on ${r.page}` : "low CTR vs position"
+		})),
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: kept.slice(0, 1).map((r) => ({
+			kind: "fix",
+			target: r.page ? {
+				kind: "page",
+				value: r.page
+			} : {
+				kind: "query",
+				value: r.keyword
+			},
+			rationale: "Rewrite title/description to lift CTR at this position"
+		})),
+		artifact: sectionArtifact(res, "opportunity")
+	};
+}
+function buildZeroClickSection(res, max) {
+	const rows = reportRows(res).sort((a, b) => b.impressions - a.impressions);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.query
+		},
+		metrics: {
+			impressions: r.impressions,
+			position: r.position,
+			ctr: r.ctr
+		},
+		why: `0 clicks on ${r.page}`
+	}));
+	return {
+		id: "zero-click",
+		title: "Zero-click queries",
+		severity: "info",
+		summary: { magnitudeLabel: `${kept.reduce((s, r) => s + r.impressions, 0)} impressions wasted` },
+		findings,
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: [],
+		artifact: sectionArtifact(res, "zero-click")
+	};
+}
+function buildMigrationSection(res, max) {
+	const rows = reportRows(res).sort((a, b) => b.weight - a.weight);
+	const kept = rows.slice(0, max);
+	return {
+		id: "query-migration",
+		title: "Query migration",
+		severity: "info",
+		summary: {},
+		findings: kept.map((r) => ({
+			entity: {
+				kind: "page",
+				value: r.targetPage
+			},
+			metrics: {
+				weight: r.weight,
+				queryCount: r.queryCount
+			},
+			why: `migrating from ${r.sourcePage}`
+		})),
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: [],
+		artifact: sectionArtifact(res, "query-migration")
+	};
+}
+export { opportunitiesReport };

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

@@ -0,0 +1,111 @@
+import { requireReportParam } from "../require.mjs";
+import { reportRows, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
+import { defineReport } from "@gscdump/engine/report";
+const DEFAULT_MAX = 10;
+const prePublishReport = defineReport({
+	id: "pre-publish",
+	description: "Pre-publish guard: cannibalization risk and striking-distance peers for a candidate topic or URL.",
+	defaultPeriod: "last-90d",
+	defaultComparison: "none",
+	argsSpec: {
+		"topic": {
+			type: "string",
+			description: "Topic / keyword / URL slug to check",
+			required: true
+		},
+		"max-findings": {
+			type: "number",
+			description: "Cap findings per section",
+			default: DEFAULT_MAX
+		}
+	},
+	plan: (params, window) => {
+		requireReportParam("pre-publish", "topic", params.topic, "pre-publish report requires --topic <topic-or-url>");
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [{
+			key: "cannibalization",
+			type: "cannibalization",
+			params: {
+				...dates,
+				limit: 200
+			}
+		}, {
+			key: "striking",
+			type: "striking-distance",
+			params: {
+				...dates,
+				limit: 200
+			}
+		}];
+	},
+	reduce: (results, ctx) => {
+		const topic = (ctx.params.topic ?? "").trim().toLowerCase();
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX;
+		const matches = (val) => !!val && val.toLowerCase().includes(topic);
+		return { sections: [buildCannibalizationSection(results.cannibalization, matches, max), buildStrikingPeersSection(results.striking, matches, max, topic)] };
+	}
+});
+function buildCannibalizationSection(res, matches, max) {
+	const rows = reportRows(res).filter((r) => matches(r.keyword) || (r.competitors ?? []).some((p) => matches(p.url))).sort((a, b) => b.totalClicks - a.totalClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => {
+		const pageCount = r.competitorCount ?? r.competitors?.length ?? 0;
+		return {
+			entity: {
+				kind: "query",
+				value: r.keyword
+			},
+			metrics: {
+				pages: pageCount,
+				totalClicks: r.totalClicks,
+				totalImpressions: r.totalImpressions
+			},
+			why: `${pageCount} page(s) already targeting`
+		};
+	});
+	return {
+		id: "cannibalization-risk",
+		title: "Cannibalization risk",
+		severity: kept.length ? "high" : "info",
+		summary: { magnitudeLabel: kept.length ? `${kept.length} existing competition` : "no existing competition" },
+		findings,
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: kept.slice(0, 1).map(() => ({
+			kind: "fix",
+			rationale: "Decide before publishing: redirect existing page, target a different angle, or accept overlap."
+		})),
+		artifact: sectionArtifact(res, "cannibalization")
+	};
+}
+function buildStrikingPeersSection(res, matches, max, topic) {
+	const rows = reportRows(res).filter((r) => matches(r.keyword) || matches(r.page)).sort((a, b) => b.potentialClicks - a.potentialClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			position: r.position,
+			impressions: r.impressions,
+			potentialClicks: r.potentialClicks
+		},
+		why: r.page ? `currently on ${r.page}` : void 0
+	}));
+	return {
+		id: "striking-peers",
+		title: "Existing striking-distance peers",
+		severity: kept.length ? "low" : "info",
+		summary: { magnitudeLabel: kept.length ? `${kept.length} adjacent rankings for "${topic}"` : "no adjacent rankings" },
+		findings,
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: [],
+		artifact: sectionArtifact(res, "striking-distance")
+	};
+}
+export { prePublishReport };

package/dist/report/reports/priority.mjs

@@ -0,0 +1,97 @@
+import { DEFAULT_PRIORITY_SOURCES, mergePriorityActions, normalizePriorityActions, scorePriorityActions } from "../../action-priority.mjs";
+import { defineReport } from "@gscdump/engine/report";
+const DEFAULT_LIMIT = 40;
+const DEFAULT_ACTIONS = 10;
+const priorityReport = defineReport({
+	id: "priority",
+	description: "Ranked priority actions composed from striking-distance, opportunity, cannibalization, ctr-anomaly, and change-point signals.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "prev-period",
+	argsSpec: {
+		"limit": {
+			type: "number",
+			description: "Max actions in the section",
+			default: DEFAULT_LIMIT
+		},
+		"max-actions": {
+			type: "number",
+			description: "Top-N rendered as ReportAction",
+			default: DEFAULT_ACTIONS
+		}
+	},
+	plan: (_params, window) => {
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		const cmp = window.comparison ? {
+			prevStartDate: window.comparison.start,
+			prevEndDate: window.comparison.end
+		} : {};
+		return DEFAULT_PRIORITY_SOURCES.map((source) => ({
+			key: source,
+			type: source,
+			params: {
+				...dates,
+				...cmp,
+				limit: 100
+			},
+			required: false
+		}));
+	},
+	reduce: (results, ctx) => {
+		const limit = ctx.params.limit ?? DEFAULT_LIMIT;
+		const maxActions = ctx.params.maxActions ?? DEFAULT_ACTIONS;
+		const all = [];
+		let anyMissing = false;
+		for (const source of DEFAULT_PRIORITY_SOURCES) {
+			const r = results[source];
+			if (!r) {
+				anyMissing = true;
+				continue;
+			}
+			all.push(...normalizePriorityActions(source, r));
+		}
+		const ranked = scorePriorityActions(mergePriorityActions(all)).slice(0, limit);
+		const findings = ranked.map((a) => ({
+			entity: {
+				kind: "query",
+				value: a.keyword
+			},
+			metrics: {
+				priorityScore: a.priorityScore,
+				severity: a.severity,
+				impact: a.impact,
+				impressions: a.impressions
+			},
+			why: `${a.title} — ${a.why} (page: ${a.page})`
+		}));
+		const actions = ranked.slice(0, maxActions).map((a) => {
+			const primarySource = a.sources[0];
+			return {
+				kind: primarySource === "cannibalization" ? "fix" : "analyzer",
+				target: {
+					kind: "page",
+					value: a.page
+				},
+				params: { type: primarySource },
+				rationale: a.title
+			};
+		});
+		const topSeverity = ranked[0]?.severity ?? 0;
+		return { sections: [{
+			id: "priority",
+			title: "Priority actions",
+			severity: topSeverity >= 70 ? "high" : topSeverity >= 40 ? "medium" : ranked.length ? "low" : "info",
+			summary: { magnitudeLabel: `${ranked.length} actions ranked` },
+			findings,
+			truncated: all.length > ranked.length ? {
+				kept: ranked.length,
+				total: all.length
+			} : void 0,
+			coverage: anyMissing ? "partial" : "full",
+			actions
+		}] };
+	}
+});
+export { priorityReport };

package/dist/report/reports/risks.mjs

@@ -0,0 +1,201 @@
+import { requireComparisonWindow } from "../require.mjs";
+import { reportRows, sectionArtifact, sectionCoverage, truncation } from "../sections.mjs";
+import { defineReport } from "@gscdump/engine/report";
+const DEFAULT_MAX = 5;
+const risksReport = defineReport({
+	id: "risks",
+	description: "Decay, cannibalization, dark-traffic and device-gap risks vs prior period.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "prev-period",
+	argsSpec: { "max-findings": {
+		type: "number",
+		description: "Cap findings per section",
+		default: DEFAULT_MAX
+	} },
+	plan: (_params, window) => {
+		const comparison = requireComparisonWindow("risks", window, "risks report requires a comparison window — pass --vs prev-period");
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		const prev = {
+			prevStartDate: comparison.start,
+			prevEndDate: comparison.end
+		};
+		return [
+			{
+				key: "decay",
+				type: "decay",
+				params: {
+					...dates,
+					...prev,
+					limit: 100
+				},
+				required: true
+			},
+			{
+				key: "cannibalization",
+				type: "cannibalization",
+				params: {
+					...dates,
+					limit: 50
+				}
+			},
+			{
+				key: "dark-traffic",
+				type: "dark-traffic",
+				params: {
+					...dates,
+					limit: 50
+				}
+			},
+			{
+				key: "device-gap",
+				type: "device-gap",
+				params: {
+					...dates,
+					limit: 50
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX;
+		return { sections: [
+			buildDecaySection(results.decay, max),
+			buildCannibalizationSection(results.cannibalization, max),
+			buildDarkTrafficSection(results["dark-traffic"], max),
+			buildDeviceGapSection(results["device-gap"], max)
+		] };
+	}
+});
+function buildDecaySection(res, max) {
+	const rows = reportRows(res).sort((a, b) => b.lostClicks - a.lostClicks);
+	const kept = rows.slice(0, max);
+	const totalLost = kept.reduce((s, r) => s + r.lostClicks, 0);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.page
+		},
+		metrics: {
+			lostClicks: r.lostClicks,
+			currentClicks: r.currentClicks,
+			declinePercent: r.declinePercent
+		},
+		delta: {
+			metric: "clicks",
+			prior: r.previousClicks,
+			current: r.currentClicks,
+			pct: -r.declinePercent * 100
+		}
+	}));
+	return {
+		id: "decay",
+		title: "Decaying pages",
+		severity: totalLost >= 200 ? "high" : totalLost >= 50 ? "medium" : "low",
+		summary: {
+			delta: -totalLost,
+			direction: totalLost > 0 ? "down" : "flat",
+			magnitudeLabel: `${Math.round(totalLost)} clicks lost`
+		},
+		findings,
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: kept.slice(0, 1).map((r) => ({
+			kind: "analyzer",
+			target: {
+				kind: "page",
+				value: r.page
+			},
+			params: { type: "change-point" },
+			rationale: "Investigate change-point on the worst-affected page"
+		})),
+		artifact: sectionArtifact(res, "decay")
+	};
+}
+function buildCannibalizationSection(res, max) {
+	const rows = reportRows(res).sort((a, b) => b.totalClicks - a.totalClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => {
+		const pageCount = r.competitorCount ?? r.competitors?.length ?? 0;
+		return {
+			entity: {
+				kind: "query",
+				value: r.keyword
+			},
+			metrics: {
+				pages: pageCount,
+				totalClicks: r.totalClicks,
+				totalImpressions: r.totalImpressions
+			},
+			why: `${pageCount} pages competing`
+		};
+	});
+	return {
+		id: "cannibalization",
+		title: "Cannibalizing queries",
+		severity: kept.length ? "medium" : "info",
+		summary: {},
+		findings,
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: [],
+		artifact: sectionArtifact(res, "cannibalization")
+	};
+}
+function buildDarkTrafficSection(res, max) {
+	const rows = reportRows(res).sort((a, b) => b.darkClicks - a.darkClicks);
+	const kept = rows.slice(0, max);
+	const totalDark = kept.reduce((s, r) => s + r.darkClicks, 0);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.url
+		},
+		metrics: {
+			darkClicks: r.darkClicks,
+			darkPercent: r.darkPercent,
+			totalClicks: r.totalClicks
+		}
+	}));
+	return {
+		id: "dark-traffic",
+		title: "Dark traffic",
+		severity: kept.length ? "low" : "info",
+		summary: { magnitudeLabel: `${Math.round(totalDark)} unattributed clicks` },
+		findings,
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: [],
+		artifact: sectionArtifact(res, "dark-traffic")
+	};
+}
+function buildDeviceGapSection(res, max) {
+	const rows = reportRows(res).sort((a, b) => Math.abs(b.gaps.positionGap) - Math.abs(a.gaps.positionGap));
+	const kept = rows.slice(0, max);
+	return {
+		id: "device-gap",
+		title: "Device gap",
+		severity: "info",
+		summary: {},
+		findings: kept.map((r) => ({
+			entity: {
+				kind: "page",
+				value: r.date
+			},
+			metrics: {
+				ctrGap: r.gaps.ctrGap,
+				positionGap: r.gaps.positionGap,
+				desktopCtr: r.desktop.ctr,
+				mobileCtr: r.mobile.ctr
+			},
+			why: `desktop vs mobile delta`
+		})),
+		truncated: truncation(rows.length, kept.length),
+		coverage: sectionCoverage(res),
+		actions: [],
+		artifact: sectionArtifact(res, "device-gap")
+	};
+}
+export { risksReport };