@gscdump/analysis 0.9.1 → 0.10.0

package/README.md

@@ -22,8 +22,6 @@ npm install @gscdump/analysis
 | `@gscdump/analysis/source` | Portable query sources (`createInMemoryQuerySource`, `createCompositeSource`) + source-backed analyzers. |
 | `@gscdump/analysis/semantic` | Browser-only semantic analyzers such as content-gap; optional `@huggingface/transformers` peer. |
 | `@gscdump/analysis/query` | `buildDataQueryPlan` / `buildDataDetailPlan` for the generic query analyzers. |
-| `@gscdump/analysis/routing` | Phase-aware D1 ↔ R2 routing helpers. |
-| `@gscdump/analysis/rollups` | Pre-baked rollup definitions + rebuild orchestration. |
 
 The contract layer (`Analyzer`, `Plan`, `Capability`, `AnalysisParams`, `AnalysisResult`, `AnalysisQuerySource`, `runAnalyzerFromSource`, `createAnalyzerRegistry`, `defineAnalyzer`, period helpers, `createEngineQuerySource`) lives in `@gscdump/engine` under the `/analyzer`, `/analysis-types`, `/period`, `/source`, and `/resolver` subpaths. Most are re-exported from `@gscdump/analysis` for convenience.
 
@@ -40,11 +38,9 @@ import {
   analyzeMovers,
   analyzeOpportunity,
   analyzeSeasonality,
-  analyzeStrikingDistance,
   padTimeseries,
 } from '@gscdump/analysis'
 
-const striking = analyzeStrikingDistance(keywordRows, { minImpressions: 100 })
 const movers = analyzeMovers(currentRows, previousRows)
 const decay = analyzeDecay(currentRows, previousRows)
 ```
@@ -72,7 +68,7 @@ const result = await runReport(report, {
 Source adapters compose a GSC client + analyzer in one call:
 
 ```ts
-import { analyzeMoversFromSource, analyzeStrikingDistanceFromSource } from '@gscdump/analysis'
+import { analyzeMoversFromSource } from '@gscdump/analysis'
 import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
 
 const source = createGscApiQuerySource({ client, siteUrl })
@@ -99,9 +95,17 @@ const result = await runAnalyzerFromSource(source, { type: 'striking-distance',
 
 ```ts
 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, { schema: 'gsc' }, { type: 'striking-distance' })
+const result = await analyzeInBrowser(
+  runner,
+  { schema: 'gsc' },
+  { type: 'striking-distance' },
+  defaultAnalyzerRegistry,
+)
 ```
 
 `analyzeInBrowser` wraps any runner with `query(sql, params, signal?)` in an `AnalysisQuerySource` with the `attachedTables` capability and dispatches via `runAnalyzerFromSource`.
@@ -178,10 +182,10 @@ Presets: `last-7d`, `last-28d`, `last-30d`, `last-90d`, `last-180d`, `last-365d`
 
 | Surface | Stability |
 |---|---|
-| Row analyzers (`analyzeStrikingDistance`, `analyzeMovers`, ...) | Public |
+| Row analyzers (`analyzeMovers`, `analyzeDecay`, ...) | Public |
 | Source factories + `analyzeFromSource` | Public |
 | `Analyzer<P, R>` contract + `createAnalyzerRegistry` (re-exported from `@gscdump/engine/analyzer`) | Public |
-| `/source`, `/semantic`, `/query`, `/routing`, `/rollups` subpaths | Public |
+| `/source`, `/semantic`, `/query` subpaths | Public |
 | Per-analyzer modules under `analysis/src/analyzers/<name>` | Private |
 
 ## Related

package/dist/analyzer/index.d.mts

@@ -1,5 +1,4 @@
 import * as _$_gscdump_engine_analyzer0 from "@gscdump/engine/analyzer";
-import { Analyzer } from "@gscdump/engine/analyzer";
 import { AnalysisPeriod } from "@gscdump/engine/period";
 import { BuilderState } from "gscdump/query";
 import { Row } from "@gscdump/engine/contracts";
@@ -748,5 +747,4 @@ declare function resolveSort<K extends string>(input: {
   sortBy: K;
   sortDir: 'asc' | 'desc';
 };
-declare const ROW_ANALYZERS: readonly Analyzer[];
-export { type BayesianCtrResult, type BipartitePagerankNode, type BipartitePagerankResult, type BrandResultRow, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ChangePointResult, type ChangePointSeriesPoint, type ClusterType, type ClusteringOptions, type ClusteringResult, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type ContentVelocityWeek, type CtrAnomalyResult, type CtrAnomalySeriesPoint, type CtrCurveBucket, type CtrCurveOutlier, type DarkTrafficResult, type DataDetailResult, type DataQueryResult, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DeviceGapResult, type IntentAtlasResult, type KeywordBreadthResult, type KeywordCluster, type LongTailResult, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversResultRow, type MoversSeriesPoint, type MoversSortMetric, type OpportunityResult, type PaginateInput, type PositionDistributionResult, type PositionVolatilityDay, type PositionVolatilityResult, type QueryMigrationExample, type QueryMigrationResult, ROW_ANALYZERS, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type StlDecomposeResult, type StlDecomposeSeriesPoint, type StrikingDistanceInputRow, type StrikingDistanceResult, type SurvivalCurvePoint, type SurvivalResult, type TrendCategory, type TrendSeriesPoint, type TrendsResult, type ZeroClickResult, bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, keywordsQueryState, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queryMigrationAnalyzer, resolveSort, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };
+export { type BayesianCtrResult, type BipartitePagerankNode, type BipartitePagerankResult, type BrandResultRow, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ChangePointResult, type ChangePointSeriesPoint, type ClusterType, type ClusteringOptions, type ClusteringResult, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type ContentVelocityWeek, type CtrAnomalyResult, type CtrAnomalySeriesPoint, type CtrCurveBucket, type CtrCurveOutlier, type DarkTrafficResult, type DataDetailResult, type DataQueryResult, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DeviceGapResult, type IntentAtlasResult, type KeywordBreadthResult, type KeywordCluster, type LongTailResult, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversResultRow, type MoversSeriesPoint, type MoversSortMetric, type OpportunityResult, type PaginateInput, type PositionDistributionResult, type PositionVolatilityDay, type PositionVolatilityResult, type QueryMigrationExample, type QueryMigrationResult, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type StlDecomposeResult, type StlDecomposeSeriesPoint, type StrikingDistanceInputRow, type StrikingDistanceResult, type SurvivalCurvePoint, type SurvivalResult, type TrendCategory, type TrendSeriesPoint, type TrendsResult, type ZeroClickResult, bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, keywordsQueryState, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queryMigrationAnalyzer, resolveSort, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };

package/dist/analyzer/index.mjs

@@ -1,11 +1,11 @@
-import { defineAnalyzer } from "@gscdump/engine/analyzer";
+import { defineAnalyzer, requireAdapter } from "@gscdump/engine/analyzer";
 import { comparisonOf, defaultEndDate, padTimeseries, periodOf } from "@gscdump/engine/period";
 import { enumeratePartitions } from "@gscdump/engine/planner";
 import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
 import { num } from "@gscdump/engine/analysis-types";
 import { between, date, extractDateRange, gsc, page, query } from "gscdump/query";
 import { MS_PER_DAY, daysAgo, toIsoDate } from "gscdump";
-import { buildExtrasQueries, buildTotalsSql, mergeExtras, pgResolverAdapter, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
+import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
 function num$5(v) {
 	if (typeof v === "number") return v;
 	if (typeof v === "bigint") return Number(v);
@@ -2098,8 +2098,7 @@ function buildDataQueryPlan(params, options) {
 			tableKey,
 			sql: comparison.sql,
 			params: comparison.params,
-			extraQueries,
-			shape: (rows, _params, resolvedExtras) => shapeDataQuery(rows, resolvedExtras, { hasPrev: true })
+			extraQueries
 		};
 	}
 	const optimized = resolveToSQLOptimized(state, options);
@@ -2107,10 +2106,12 @@ function buildDataQueryPlan(params, options) {
 		tableKey,
 		sql: optimized.sql,
 		params: optimized.params,
-		extraQueries,
-		shape: (rows, _params, resolvedExtras) => shapeDataQuery(rows, resolvedExtras, { hasPrev: false })
+		extraQueries
 	};
 }
+function shapeDataQueryRows(rows, params, extras) {
+	return shapeDataQuery(rows, extras, { hasPrev: params.qc != null });
+}
 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");
@@ -2130,46 +2131,53 @@ function buildDataDetailPlan(params, options) {
 			params: previousTotals.params
 		});
 	}
-	const tableKey = options.adapter.inferTable(state.dimensions);
-	const { startDate: rangeStart, endDate: rangeEnd } = extractDateRange(state.filter);
 	return {
-		tableKey,
+		tableKey: options.adapter.inferTable(state.dimensions),
 		sql: main.sql,
 		params: main.params,
-		extraQueries,
-		shape: (rows, _params, extras) => {
-			const coerced = rows.map(coerceNumericCols);
-			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)
-			} };
-			if (extras?.prevTotals) {
-				const previousTotalsRow = extras.prevTotals[0] ?? {};
-				meta.previousTotals = {
-					clicks: Number(previousTotalsRow.clicks ?? 0),
-					impressions: Number(previousTotalsRow.impressions ?? 0),
-					ctr: Number(previousTotalsRow.ctr ?? 0),
-					position: Number(previousTotalsRow.position ?? 0)
-				};
-			}
-			return {
-				results: daily,
-				meta
-			};
-		}
+		extraQueries
+	};
+}
+function shapeDataDetailRows(rows, params, extras) {
+	const { startDate: rangeStart, endDate: rangeEnd } = extractDateRange(requireBuilderState(params.q, "data-detail").filter);
+	const coerced = rows.map(coerceNumericCols);
+	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)
+	} };
+	if (extras?.prevTotals) {
+		const previousTotalsRow = extras.prevTotals[0] ?? {};
+		meta.previousTotals = {
+			clicks: Number(previousTotalsRow.clicks ?? 0),
+			impressions: Number(previousTotalsRow.impressions ?? 0),
+			ctr: Number(previousTotalsRow.ctr ?? 0),
+			position: Number(previousTotalsRow.position ?? 0)
+		};
+	}
+	return {
+		results: daily,
+		meta
 	};
 }
 const dataDetailAnalyzer = defineAnalyzer({
 	id: "data-detail",
-	buildSql(params) {
-		const plan = buildDataDetailPlan(params, { adapter: pgResolverAdapter });
+	sqlRequires: [
+		"executeSql",
+		"attachedTables",
+		"adapter"
+	],
+	buildSql(params, ctx) {
+		const plan = buildDataDetailPlan(params, {
+			adapter: requireAdapter(ctx, "data-detail"),
+			siteId: ctx.siteId
+		});
 		return {
 			sql: plan.sql,
 			params: plan.params,
@@ -2177,13 +2185,11 @@ const dataDetailAnalyzer = defineAnalyzer({
 				table: plan.tableKey,
 				partitions: []
 			},
-			requiresAttachedTables: true,
 			extraQueries: plan.extraQueries
 		};
 	},
 	reduceSql(rows, params, ctx) {
-		const arr = Array.isArray(rows) ? rows : [];
-		const { results, meta } = buildDataDetailPlan(params, { adapter: pgResolverAdapter }).shape(arr, params, ctx.extras);
+		const { results, meta } = shapeDataDetailRows(Array.isArray(rows) ? rows : [], params, ctx.extras);
 		return {
 			results,
 			meta
@@ -2192,8 +2198,16 @@ const dataDetailAnalyzer = defineAnalyzer({
 });
 const dataQueryAnalyzer = defineAnalyzer({
 	id: "data-query",
-	buildSql(params) {
-		const plan = buildDataQueryPlan(params, { adapter: pgResolverAdapter });
+	sqlRequires: [
+		"executeSql",
+		"attachedTables",
+		"adapter"
+	],
+	buildSql(params, ctx) {
+		const plan = buildDataQueryPlan(params, {
+			adapter: requireAdapter(ctx, "data-query"),
+			siteId: ctx.siteId
+		});
 		return {
 			sql: plan.sql,
 			params: plan.params,
@@ -2201,13 +2215,11 @@ const dataQueryAnalyzer = defineAnalyzer({
 				table: plan.tableKey,
 				partitions: []
 			},
-			requiresAttachedTables: true,
 			extraQueries: plan.extraQueries
 		};
 	},
 	reduceSql(rows, params, ctx) {
-		const arr = Array.isArray(rows) ? rows : [];
-		const { results, meta } = buildDataQueryPlan(params, { adapter: pgResolverAdapter }).shape(arr, params, ctx.extras);
+		const { results, meta } = shapeDataQueryRows(Array.isArray(rows) ? rows : [], params, ctx.extras);
 		return {
 			results,
 			meta
@@ -4148,37 +4160,39 @@ const stlDecomposeAnalyzer = defineAnalyzer({
 	}
 });
 const DEFAULT_ROW_LIMIT$1 = 25e3;
+function filterStrikingDistance(rows, options = {}) {
+	const minPosition = options.minPosition ?? 4;
+	const maxPosition = options.maxPosition ?? 20;
+	const minImpressions = options.minImpressions ?? 100;
+	const maxCtr = options.maxCtr ?? .05;
+	const results = [];
+	for (const row of rows) {
+		const position = num(row.position);
+		const impressions = num(row.impressions);
+		const ctr = num(row.ctr);
+		const clicks = num(row.clicks);
+		if (position < minPosition || position > maxPosition) continue;
+		if (impressions < minImpressions) continue;
+		if (ctr > maxCtr) continue;
+		results.push({
+			keyword: String(row.query ?? ""),
+			page: row.page == null ? null : String(row.page),
+			clicks,
+			impressions,
+			ctr,
+			position,
+			potentialClicks: Math.round(impressions * .15)
+		});
+	}
+	return results;
+}
 const strikingDistanceAnalyzer = defineAnalyzer({
 	id: "striking-distance",
 	reduce(rows, params) {
-		const arr = Array.isArray(rows) ? rows : [];
-		const minPosition = params.minPosition ?? 4;
-		const maxPosition = params.maxPosition ?? 20;
-		const minImpressions = params.minImpressions ?? 100;
-		const maxCtr = params.maxCtr ?? .05;
-		const limit = params.limit ?? 1e3;
-		const results = [];
-		for (const row of arr) {
-			const position = num(row.position);
-			const impressions = num(row.impressions);
-			const ctr = num(row.ctr);
-			const clicks = num(row.clicks);
-			if (position < minPosition || position > maxPosition) continue;
-			if (impressions < minImpressions) continue;
-			if (ctr > maxCtr) continue;
-			results.push({
-				keyword: String(row.query ?? ""),
-				page: row.page == null ? null : String(row.page),
-				clicks,
-				impressions,
-				ctr,
-				position,
-				potentialClicks: Math.round(impressions * .15)
-			});
-		}
+		const results = filterStrikingDistance(Array.isArray(rows) ? rows : [], params);
 		results.sort((a, b) => b.potentialClicks - a.potentialClicks);
 		const paged = paginateInMemory(results, {
-			limit,
+			limit: params.limit ?? 1e3,
 			offset: params.offset
 		});
 		return {
@@ -4695,16 +4709,4 @@ const zeroClickAnalyzer = defineAnalyzer({
 		};
 	}
 });
-const ROW_ANALYZERS = [
-	strikingDistanceAnalyzer.rows,
-	opportunityAnalyzer.rows,
-	brandAnalyzer.rows,
-	concentrationAnalyzer.rows,
-	clusteringAnalyzer.rows,
-	seasonalityAnalyzer.rows,
-	moversAnalyzer.rows,
-	decayAnalyzer.rows,
-	cannibalizationAnalyzer.rows,
-	zeroClickAnalyzer.rows
-];
-export { ROW_ANALYZERS, bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, keywordsQueryState, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queryMigrationAnalyzer, resolveSort, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };
+export { bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, keywordsQueryState, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queryMigrationAnalyzer, resolveSort, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };

package/dist/default-registry.d.mts

@@ -1,9 +1,9 @@
 import * as _$_gscdump_engine_analyzer0 from "@gscdump/engine/analyzer";
 /**
- * Default analyzer registry built from every in-tree analyzer: row analyzers
- * plus DuckDB SQL analyzers. Convenience for callers who don't care about
- * bundle size; edge / browser consumers should compose their own narrower
- * registry via `createAnalyzerRegistry`.
+ * Default analyzer registry built from every in-tree analyzer. Convenience
+ * for callers who don't care about bundle size; edge / browser consumers
+ * should compose their own narrower registry via `createAnalyzerRegistry`
+ * with the flat `ROW_ANALYZERS` / `SQL_ANALYZERS` arrays.
  */
 declare const defaultAnalyzerRegistry: _$_gscdump_engine_analyzer0.AnalyzerRegistry;
 export { defaultAnalyzerRegistry };