@gscdump/analysis 0.38.2 → 0.40.1

package/README.md

@@ -89,7 +89,9 @@ const registry = createAnalyzerRegistry({ rows: ROW_ANALYZERS, sql: SQL_ANALYZER
 const result = await runAnalyzerFromSource(source, { type: 'striking-distance', minImpressions: 100 }, registry)
 ```
 
-`attachParquetIndex` and `attachSnapshotIndex` from `@gscdump/engine-duckdb-node` wire parquet files (per-day, per-month, or pre-baked `.duckdb` snapshots) into a DuckDB session. Pair with `analyzeInBrowser` from `@gscdump/analysis` for the attached-table dispatch path.
+`attachParquetIndex` and `attachSnapshotIndex` from `@gscdump/engine/node`
+wire parquet files (per-day, per-month, or pre-baked `.duckdb` snapshots) into
+a Node DuckDB session.
 
 ## Browser (DuckDB-WASM)
 
@@ -98,7 +100,6 @@ import { analyzeInBrowser } from '@gscdump/analysis'
 // Compose your own narrow registry instead of pulling the kitchen-sink default
 // (which statically imports every SQL analyzer). For demo only:
 import { defaultAnalyzerRegistry } from '@gscdump/analysis/registry'
-import { createEngine } from '@gscdump/engine-duckdb-wasm'
 
 const result = await analyzeInBrowser(
   runner,
@@ -110,7 +111,10 @@ const result = await analyzeInBrowser(
 
 `analyzeInBrowser` wraps any runner with `query(sql, params, signal?)` in an `AnalysisQuerySource` with the `attachedTables` capability and dispatches via `runAnalyzerFromSource`.
 
-For typed drizzle-style access, `@gscdump/engine-duckdb-wasm` exports `createEngine` (a `SqlQuerySource`) plus `bootDuckDBWasm`, `attachParquetUrlTables`, `createBrowserAnalysisRuntime`, and `resolveWindow` (re-export from `@gscdump/engine/period`).
+`@gscdump/engine-duckdb-wasm` exports `bootDuckDBWasm`,
+`attachParquetUrlTables`, `createBrowserAnalysisRuntime`, and `resolveWindow`
+(re-exported from `@gscdump/engine/period`). Browser analysis uses attached
+tables rather than a canonical-schema `createEngine`; see ADR-0001.
 
 ## SQLite (D1 / Cloudflare Workers)
 
@@ -148,7 +152,7 @@ Available source factories:
 - `createCompositeSource({ engine, gsc })` — `@gscdump/analysis/source`; engine first, GSC fallback
 - `createInMemoryQuerySource({ queryRows })` — `@gscdump/analysis/source`
 - `createEngineQuerySource({ engine, ctx })` — `@gscdump/engine/source`
-- `createEngine({ ... })` — `@gscdump/engine-duckdb-wasm`, `@gscdump/engine-sqlite`, `@gscdump/engine-duckdb-node`
+- `createEngine({ ... })` — `@gscdump/engine-sqlite`
 
 Portable analyzers currently cover the row-based tools:
 `striking-distance`, `opportunity`, `brand`, `clustering`, `concentration`,
@@ -192,7 +196,7 @@ Presets: `last-7d`, `last-28d`, `last-30d`, `last-90d`, `last-180d`, `last-365d`
 
 - [`gscdump`](../gscdump) — REST client + query builder (edge-safe).
 - [`@gscdump/engine`](../engine) — Parquet/DuckDB storage engine + analyzer/source/period contracts.
-- [`@gscdump/engine-duckdb-node`](../engine-duckdb-node) — Node DuckDB engine factory + parquet/snapshot attach helpers.
+- [`@gscdump/engine/node`](../engine) — Node DuckDB handle + parquet/snapshot attach helpers.
 - [`@gscdump/engine-duckdb-wasm`](../engine-duckdb-wasm) — DuckDB-WASM browser runtime + drizzle adapter.
 - [`@gscdump/engine-sqlite`](../engine-sqlite) — SQLite / D1 dialect adapter.
 - [`@gscdump/engine-gsc-api`](../engine-gsc-api) — GSC live-API engine adapter.

package/dist/analyzer/index.d.mts

@@ -81,6 +81,13 @@ interface BrandSegmentationOptions {
   /** Minimum impressions for a keyword to be included. Default: 10 */
   minImpressions?: number;
 }
+interface BrandSegmentationRow {
+  query?: string;
+  keyword?: string;
+  variants?: readonly string[];
+  clicks?: number | null;
+  impressions?: number | null;
+}
 interface BrandSummary {
   brandClicks: number;
   nonBrandClicks: number;
@@ -88,9 +95,9 @@ interface BrandSummary {
   brandImpressions: number;
   nonBrandImpressions: number;
 }
-interface BrandSegmentationResult {
-  brand: QueriesRow[];
-  nonBrand: QueriesRow[];
+interface BrandSegmentationResult<T extends BrandSegmentationRow = QueriesRow> {
+  brand: T[];
+  nonBrand: T[];
   summary: BrandSummary;
 }
 interface BrandResultRow {
@@ -698,12 +705,6 @@ interface TrendsResult {
   series: TrendSeriesPoint[];
 }
 declare const trendsAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * `zero-click` — high impressions, low CTR, good ranking. SQL groups by
- * (query, url) and applies HAVING/WHERE pushdown; row reducer dedupes to the
- * best-positioned page per query (different semantics, kept for parity with
- * the existing live-GSC behavior).
- */
 interface ZeroClickResult {
   query: string;
   page: string;

package/dist/analyzer/index.mjs

@@ -6,7 +6,7 @@ import { num } from "@gscdump/engine/analysis-types";
 import { err, ok, unwrapResult } from "gscdump/result";
 import { between, date, extractDateRange, gsc, page, query } from "gscdump/query";
 import { MS_PER_DAY, daysAgoUtc, toIsoDate } from "gscdump/dates";
-import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
+import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
 function rowNumber(value) {
 	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
 	if (typeof value === "bigint") return Number(value);
@@ -522,8 +522,7 @@ function analyzeBrandSegmentation(keywords, options) {
 		const impressions = num(row.impressions);
 		if (impressions < minImpressions) continue;
 		const clicks = num(row.clicks);
-		const query = row.query.toLowerCase();
-		if (lowerBrandTerms.some((term) => query.includes(term))) {
+		if ((row.variants?.length ? row.variants : [row.query ?? row.keyword ?? ""]).some((query) => lowerBrandTerms.some((term) => query.toLowerCase().includes(term)))) {
 			brand.push(row);
 			brandClicks += clicks;
 			brandImpressions += impressions;
@@ -665,7 +664,7 @@ function createMetricSorter(defaultMetric, orderByMetric) {
 		return [...items].sort((a, b) => (a[sortBy] - b[sortBy]) * mult);
 	};
 }
-const sortRowResults$1 = createSorter((item, metric) => {
+const sortRowResults = createSorter((item, metric) => {
 	switch (metric) {
 		case "clicks": return item.totalClicks;
 		case "impressions": return item.totalImpressions;
@@ -712,7 +711,7 @@ function analyzeCannibalization(rows, options = {}) {
 			positionSpread
 		});
 	}
-	return sortRowResults$1(results, sortBy, sortOrder);
+	return sortRowResults(results, sortBy, sortOrder);
 }
 const cannibalizationAnalyzer = defineAnalyzer({
 	id: "cannibalization",
@@ -2250,14 +2249,9 @@ function shapeDataQueryRows(rows, params, extras) {
 function buildDataDetailPlan(params, options) {
 	const state = requireBuilderState(params.q, "data-detail");
 	if (!state.dimensions.includes("date")) throw new Error("data-detail: `date` dimension is required");
-	const main = resolveToSQL(state, options);
-	const totals = buildTotalsSql(state, options);
+	const main = resolveToSQLOptimized(state, options);
 	const prev = optionalBuilderState(params.qc, "data-detail", "qc");
-	const extraQueries = [{
-		name: "totals",
-		sql: totals.sql,
-		params: totals.params
-	}];
+	const extraQueries = [];
 	if (prev) {
 		const previousTotals = buildTotalsSql(prev, options);
 		extraQueries.push({
@@ -2275,18 +2269,22 @@ function buildDataDetailPlan(params, options) {
 }
 function shapeDataDetailRows(rows, params, extras) {
 	const { startDate: rangeStart, endDate: rangeEnd } = extractDateRange(requireBuilderState(params.q, "data-detail").filter);
-	const coerced = rows.map(coerceNumericCols);
+	const first = rows[0];
+	const totals = {
+		clicks: Number(first?.totalClicks ?? 0),
+		impressions: Number(first?.totalImpressions ?? 0),
+		ctr: Number(first?.totalCtr ?? 0),
+		position: Number(first?.totalPosition ?? 0)
+	};
+	const coerced = rows.map((raw) => {
+		const { totalCount: _tc, totalClicks: _tclk, totalImpressions: _timp, totalCtr: _tctr, totalPosition: _tpos, sum_position: _sp, ...rest } = raw;
+		return coerceNumericCols(rest);
+	});
 	const daily = rangeStart && rangeEnd ? padTimeseries(coerced, {
 		startDate: rangeStart,
 		endDate: rangeEnd
 	}) : coerced;
-	const totalsRow = extras?.totals?.[0] ?? {};
-	const meta = { totals: {
-		clicks: Number(totalsRow.clicks ?? 0),
-		impressions: Number(totalsRow.impressions ?? 0),
-		ctr: Number(totalsRow.ctr ?? 0),
-		position: Number(totalsRow.position ?? 0)
-	} };
+	const meta = { totals };
 	if (extras?.prevTotals) {
 		const previousTotalsRow = extras.prevTotals[0] ?? {};
 		meta.previousTotals = {
@@ -2403,13 +2401,75 @@ function paginateInMemory(rows, input) {
 	const o = clampOffset(input.offset);
 	return rows.slice(o, o + l);
 }
+function paginateSortedInMemory(rows, input, compare) {
+	const limit = clampLimit(input.limit, rows.length);
+	const offset = clampOffset(input.offset);
+	const selectedCount = Math.min(rows.length, offset + limit);
+	if (limit === 0 || offset >= rows.length || selectedCount === 0) return [];
+	const fullSort = () => [...rows].sort(compare).slice(offset, offset + limit);
+	if (selectedCount >= rows.length / 2) return fullSort();
+	let invalidComparison = false;
+	const compareStable = (left, right) => {
+		const order = compare(left.value, right.value);
+		if (Number.isNaN(order)) {
+			invalidComparison = true;
+			return left.index - right.index;
+		}
+		return order || left.index - right.index;
+	};
+	const isWorse = (left, right) => compareStable(left, right) > 0;
+	const heap = [];
+	const siftUp = (start) => {
+		let index = start;
+		while (index > 0) {
+			const parent = index - 1 >>> 1;
+			if (!isWorse(heap[index], heap[parent])) break;
+			const swap = heap[parent];
+			heap[parent] = heap[index];
+			heap[index] = swap;
+			index = parent;
+		}
+	};
+	const siftDown = () => {
+		let index = 0;
+		for (;;) {
+			const left = index * 2 + 1;
+			if (left >= heap.length) return;
+			const right = left + 1;
+			let worse = left;
+			if (right < heap.length && isWorse(heap[right], heap[left])) worse = right;
+			if (!isWorse(heap[worse], heap[index])) return;
+			const swap = heap[index];
+			heap[index] = heap[worse];
+			heap[worse] = swap;
+			index = worse;
+		}
+	};
+	for (let index = 0; index < rows.length; index++) {
+		const candidate = {
+			value: rows[index],
+			index
+		};
+		if (heap.length < selectedCount) {
+			heap.push(candidate);
+			siftUp(heap.length - 1);
+		} else if (compareStable(candidate, heap[0]) < 0) {
+			heap[0] = candidate;
+			siftDown();
+		}
+	}
+	if (invalidComparison) return fullSort();
+	heap.sort(compareStable);
+	if (invalidComparison) return fullSort();
+	return heap.slice(offset, offset + limit).map((entry) => entry.value);
+}
 function resolveSort(input, allowed, defaults) {
 	return {
 		sortBy: input.sortBy && allowed.includes(input.sortBy) ? input.sortBy : defaults.sortBy,
 		sortDir: input.sortDir === "asc" || input.sortDir === "desc" ? input.sortDir : defaults.sortDir
 	};
 }
-const sortResults$1 = createMetricSorter("lostClicks", {
+const sortResults = createMetricSorter("lostClicks", {
 	lostClicks: "desc",
 	declinePercent: "desc",
 	currentClicks: "asc"
@@ -2442,7 +2502,7 @@ function analyzeDecay(input, options = {}) {
 			positionDrop: currentPosition != null ? currentPosition - prev.position : null
 		});
 	}
-	return sortResults$1(results, sortBy);
+	return sortResults(results, sortBy);
 }
 const decayAnalyzer = defineAnalyzer({
 	id: "decay",
@@ -3441,12 +3501,52 @@ function calculateCtrGapScore(actualCtr, position) {
 	const gap = expectedCtr - actualCtr;
 	return Math.min(gap / expectedCtr, 1);
 }
-const sortResults = createMetricSorter("opportunityScore", {
+const SORT_DIR = {
 	opportunityScore: "desc",
 	potentialClicks: "desc",
 	impressions: "desc",
 	position: "asc"
-});
+};
+function analyzeOpportunity(keywords, options = {}) {
+	const minImpressions = options.minImpressions ?? 100;
+	const positionWeight = options.weights?.position ?? 1;
+	const impressionsWeight = options.weights?.impressions ?? 1;
+	const ctrGapWeight = options.weights?.ctrGap ?? 1;
+	const totalWeight = positionWeight + impressionsWeight + ctrGapWeight;
+	const sortBy = options.sortBy ?? "opportunityScore";
+	const results = [];
+	for (const row of keywords) {
+		const impressions = num(row.impressions);
+		if (impressions < minImpressions) continue;
+		const position = num(row.position);
+		const ctr = num(row.ctr);
+		const clicks = num(row.clicks);
+		const positionScore = calculatePositionScore(position);
+		const impressionScore = calculateImpressionScore(impressions);
+		const ctrGapScore = calculateCtrGapScore(ctr, position);
+		const weightedProduct = positionScore ** positionWeight * impressionScore ** impressionsWeight * ctrGapScore ** ctrGapWeight;
+		const opportunityScore = Math.round(weightedProduct ** (1 / totalWeight) * 100);
+		const potentialClicks = Math.round(impressions * getExpectedCtr(Math.min(3, position)));
+		results.push({
+			keyword: row.query,
+			page: row.page ?? null,
+			clicks,
+			impressions,
+			ctr,
+			position,
+			opportunityScore,
+			potentialClicks,
+			factors: {
+				positionScore,
+				impressionScore,
+				ctrGapScore
+			}
+		});
+	}
+	const direction = SORT_DIR[sortBy];
+	results.sort((left, right) => direction === "asc" ? left[sortBy] - right[sortBy] : right[sortBy] - left[sortBy]);
+	return options.limit ? results.slice(0, options.limit) : results;
+}
 const opportunityAnalyzer = defineAnalyzer({
 	id: "opportunity",
 	buildSql(params) {
@@ -3560,51 +3660,15 @@ const opportunityAnalyzer = defineAnalyzer({
 		return { queries: queriesQueryState(periodOf(params), params.limit) };
 	},
 	reduceRows(rows, params) {
-		const keywords = (Array.isArray(rows) ? rows : []) ?? [];
-		const minImpressions = params.minImpressions ?? 100;
-		const positionWeight = 1;
-		const impressionsWeight = 1;
-		const ctrGapWeight = 1;
-		const sortBy = "opportunityScore";
-		const results = [];
-		for (const row of keywords) {
-			const impressions = num(row.impressions);
-			const position = num(row.position);
-			const ctr = num(row.ctr);
-			const clicks = num(row.clicks);
-			if (impressions < minImpressions) continue;
-			const positionScore = calculatePositionScore(position);
-			const impressionScore = calculateImpressionScore(impressions);
-			const ctrGapScore = calculateCtrGapScore(ctr, position);
-			const geometricMean = (positionScore ** positionWeight * impressionScore ** impressionsWeight * ctrGapScore ** ctrGapWeight) ** (1 / 3);
-			const opportunityScore = Math.round(geometricMean * 100);
-			const targetCtr = getExpectedCtr(Math.min(3, position));
-			const potentialClicks = Math.round(impressions * targetCtr);
-			results.push({
-				keyword: row.query,
-				page: row.page ?? null,
-				clicks,
-				impressions,
-				ctr,
-				position,
-				opportunityScore,
-				potentialClicks,
-				factors: {
-					positionScore,
-					impressionScore,
-					ctrGapScore
-				}
-			});
-		}
-		const sorted = sortResults(results, sortBy);
-		const paged = paginateInMemory(sorted, {
+		const results = analyzeOpportunity((Array.isArray(rows) ? rows : []) ?? [], { minImpressions: params.minImpressions });
+		const paged = paginateSortedInMemory(results, {
 			limit: params.limit,
 			offset: params.offset
-		});
+		}, (left, right) => right.opportunityScore - left.opportunityScore);
 		return {
 			results: paged,
 			meta: {
-				total: sorted.length,
+				total: results.length,
 				returned: paged.length
 			}
 		};
@@ -4276,6 +4340,12 @@ const stlDecomposeAnalyzer = defineAnalyzer({
 	}
 });
 const DEFAULT_ROW_LIMIT$1 = 25e3;
+function paginateStrikingDistance(results, options) {
+	return paginateSortedInMemory(results, {
+		limit: options.limit ?? 1e3,
+		offset: options.offset
+	}, (left, right) => right.potentialClicks - left.potentialClicks);
+}
 function filterStrikingDistance(rows, options = {}) {
 	const minPosition = options.minPosition ?? 4;
 	const maxPosition = options.maxPosition ?? 20;
@@ -4306,11 +4376,7 @@ const strikingDistanceAnalyzer = defineAnalyzer({
 	id: "striking-distance",
 	reduce(rows, params) {
 		const results = filterStrikingDistance(Array.isArray(rows) ? rows : [], params);
-		results.sort((a, b) => b.potentialClicks - a.potentialClicks);
-		const paged = paginateInMemory(results, {
-			limit: params.limit ?? 1e3,
-			offset: params.offset
-		});
+		const paged = paginateStrikingDistance(results, params);
 		return {
 			results: paged,
 			meta: {
@@ -4686,7 +4752,18 @@ const trendsAnalyzer = defineAnalyzer({
 	}
 });
 const DEFAULT_ROW_LIMIT = 25e3;
-const sortRowResults = createSorter((item) => item.impressions, "impressions");
+function analyzeZeroClick(rows, options = {}) {
+	const minImpressions = options.minImpressions ?? 1e3;
+	const maxCtr = options.maxCtr ?? .03;
+	const maxPosition = options.maxPosition ?? 10;
+	const queryMap = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		if (row.impressions < minImpressions || row.position > maxPosition || row.ctr > maxCtr) continue;
+		const existing = queryMap.get(row.query);
+		if (!existing || row.position < existing.position) queryMap.set(row.query, { ...row });
+	}
+	return [...queryMap.values()].sort((left, right) => right.impressions - left.impressions);
+}
 const zeroClickAnalyzer = defineAnalyzer({
 	id: "zero-click",
 	buildSql(params) {
@@ -4770,30 +4847,15 @@ const zeroClickAnalyzer = defineAnalyzer({
 		return { rows: gsc.select(query, page).where(between(date, period.startDate, period.endDate)).limit(limit).getState() };
 	},
 	reduceRows(rows, params) {
-		const arr = Array.isArray(rows) ? rows : [];
-		const minImpressions = params.minImpressions ?? 1e3;
-		const maxCtr = params.maxCtr ?? .03;
-		const maxPosition = params.maxPosition ?? 10;
-		const queryMap = /* @__PURE__ */ new Map();
-		for (const row of arr) {
-			if (row.impressions < minImpressions) continue;
-			if (row.position > maxPosition) continue;
-			if (row.ctr > maxCtr) continue;
-			const existing = queryMap.get(row.query);
-			if (!existing || row.position < existing.position) queryMap.set(row.query, {
-				query: row.query,
-				page: row.page,
-				clicks: row.clicks,
-				impressions: row.impressions,
-				ctr: row.ctr,
-				position: row.position
-			});
-		}
-		const results = sortRowResults(Array.from(queryMap.values()), "impressions", "desc");
-		const paged = paginateInMemory(results, {
+		const results = analyzeZeroClick(Array.isArray(rows) ? rows : [], {
+			minImpressions: params.minImpressions ?? 1e3,
+			maxCtr: params.maxCtr ?? .03,
+			maxPosition: params.maxPosition ?? 10
+		});
+		const paged = paginateSortedInMemory(results, {
 			limit: params.limit,
 			offset: params.offset
-		});
+		}, (left, right) => right.impressions - left.impressions);
 		return {
 			results: paged,
 			meta: {