@gscdump/analysis 0.9.1 → 0.10.0

package/dist/query/index.d.mts

@@ -11,16 +11,28 @@ interface QueryAnalyzerPlan<TK extends string = string> {
   sql: string;
   params: unknown[];
   extraQueries?: QueryAnalyzerExtraQuery[];
-  shape: (rows: Row[], params: AnalysisParams, extras?: Record<string, Row[]>) => {
-    results: Row[];
-    meta: Record<string, unknown>;
-  };
 }
 declare function buildDataQueryPlan<TK extends string>(params: AnalysisParams, options: ResolverOptions<TK>): QueryAnalyzerPlan<TK>;
+/**
+ * Pure post-processing for `data-query` rows. Adapter-free so reducers can
+ * call it without re-running the SQL plan.
+ */
+declare function shapeDataQueryRows(rows: Row[], params: AnalysisParams, extras?: Record<string, Row[]>): {
+  results: Row[];
+  meta: Record<string, unknown>;
+};
 declare function buildDataDetailPlan<TK extends string>(params: AnalysisParams, options: ResolverOptions<TK>): QueryAnalyzerPlan<TK>;
+/**
+ * Pure post-processing for `data-detail` rows. Reads the date range off
+ * `params.q` so it stays adapter-free; reducers call it directly.
+ */
+declare function shapeDataDetailRows(rows: Row[], params: AnalysisParams, extras?: Record<string, Row[]>): {
+  results: Row[];
+  meta: Record<string, unknown>;
+};
 /**
  * Produce a canonical form of a search query for grouping near-duplicates.
  * Idempotent: `normalizeQuery(normalizeQuery(q)) === normalizeQuery(q)`.
  */
 declare function normalizeQuery(query: string): string;
-export { type QueryAnalyzerExtraQuery, type QueryAnalyzerPlan, buildDataDetailPlan, buildDataQueryPlan, normalizeQuery };
+export { type QueryAnalyzerExtraQuery, type QueryAnalyzerPlan, buildDataDetailPlan, buildDataQueryPlan, normalizeQuery, shapeDataDetailRows, shapeDataQueryRows };

package/dist/query/index.mjs

@@ -88,8 +88,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);
@@ -97,10 +96,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");
@@ -120,40 +121,39 @@ 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 SYNONYMS = {
@@ -305,4 +305,4 @@ const WHITESPACE_RE = /\s+/g;
 function normalizeQuery(query) {
 	return query.toLowerCase().replace(SEPARATOR_RE, " ").replace(WHITESPACE_RE, " ").trim().split(" ").filter(Boolean).map((token) => SYNONYMS[token] ?? token).filter(Boolean).map(depluralize).sort().join(" ");
 }
-export { buildDataDetailPlan, buildDataQueryPlan, normalizeQuery };
+export { buildDataDetailPlan, buildDataQueryPlan, normalizeQuery, shapeDataDetailRows, shapeDataQueryRows };

package/dist/report/index.d.mts

@@ -1,7 +1,7 @@
 import * as _$_gscdump_engine_report0 from "@gscdump/engine/report";
 import { DefinedReport, ReportContext, ReportParams, ReportResult } from "@gscdump/engine/report";
 import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
-import { AnalysisQuerySource } from "@gscdump/engine/resolver";
+import { AnalysisQuerySource } from "@gscdump/engine/source";
 interface FormatReportOptions {
   /** Cap findings rendered per section. Defaults to all (already bounded by report). */
   maxFindingsPerSection?: number;

package/dist/report/index.mjs

@@ -1739,11 +1739,8 @@ const defaultReportRegistry = createReportRegistry({
 	reports: REPORTS,
 	version: "0"
 });
-async function analyzeFromSource(source, params, registry) {
-	return runAnalyzerFromSource(source, params, registry);
-}
 async function executeStep(source, analyzers, step) {
-	return analyzeFromSource(source, {
+	return runAnalyzerFromSource(source, {
 		...step.params,
 		type: step.type
 	}, analyzers).then((result) => ({

package/dist/semantic/index.d.mts

@@ -1,4 +1,4 @@
-import { AnalysisQuerySource } from "@gscdump/engine/resolver";
+import { AnalysisQuerySource } from "@gscdump/engine/source";
 interface ContentGapResult {
   query: string;
   impressions: number;

package/dist/source/index.d.mts

@@ -1,19 +1,16 @@
-import { AnalyzerCapabilityError, AnalyzerRegistry } from "@gscdump/engine/analyzer";
 import { BuilderState } from "gscdump/query";
-import { AnalysisParams, AnalysisResult } from "@gscdump/engine/analysis-types";
-import { AnalysisPeriod, ComparisonPeriod } from "@gscdump/engine/period";
-import { AnalysisQuerySource, QueryRow, RowQuerySource, SqlQuerySource } from "@gscdump/engine/resolver";
+import { AnalysisQuerySource, QueryRow } from "@gscdump/engine/source";
 import { PlannerCapabilities } from "gscdump/query/plan";
-declare function analyzeFromSource(source: AnalysisQuerySource, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
+interface SyncedRange {
+  oldestDateSynced: string | null;
+  newestDateSynced: string | null;
+}
 interface CompositeSourceOptions {
-  engine: SqlQuerySource;
+  engine: AnalysisQuerySource;
   live: AnalysisQuerySource;
-  site: {
-    oldestDateSynced: string | null;
-    newestDateSynced: string | null;
-  };
+  site: SyncedRange;
 }
-declare function createCompositeSource(opts: CompositeSourceOptions): SqlQuerySource;
+declare function createCompositeSource(opts: CompositeSourceOptions): AnalysisQuerySource;
 /**
  * Permissive defaults: in-memory sources are usually test doubles, so they
  * advertise every capability unless the test explicitly narrows them.
@@ -23,237 +20,5 @@ interface InMemoryQuerySourceOptions {
   queryRows: (state: BuilderState) => Promise<QueryRow[]> | QueryRow[];
   capabilities?: PlannerCapabilities;
 }
-declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): RowQuerySource;
-/**
- * Domain row shapes + analysis utilities. Analyzer-call contracts
- * (`AnalysisParams`, `AnalysisResult`, `AnalysisTool`, `num`) live in
- * `@gscdump/engine/analysis-types`.
- */
-type SortOrder = 'asc' | 'desc';
-/** Base search metrics */
-interface BaseMetrics {
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-/** Keyword row from query */
-interface KeywordRow extends BaseMetrics {
-  query: string;
-  page?: string;
-}
-/** Page row from query */
-interface PageRow extends BaseMetrics {
-  page: string;
-}
-/** Date row from query */
-interface DateRow extends BaseMetrics {
-  date: string;
-}
-interface BrandSegmentationOptions {
-  /** Brand terms to match against keywords (case-insensitive) */
-  brandTerms: string[];
-  /** Minimum impressions for a keyword to be included. Default: 10 */
-  minImpressions?: number;
-}
-interface BrandSummary {
-  brandClicks: number;
-  nonBrandClicks: number;
-  brandShare: number;
-  brandImpressions: number;
-  nonBrandImpressions: number;
-}
-interface BrandSegmentationResult {
-  brand: KeywordRow[];
-  nonBrand: KeywordRow[];
-  summary: BrandSummary;
-}
-type ClusterType = 'prefix' | 'intent' | 'both';
-interface ClusteringOptions {
-  /** Minimum keywords for a cluster to be reported. Default: 2 */
-  minClusterSize?: number;
-  /** Minimum impressions for a keyword to be included. Default: 10 */
-  minImpressions?: number;
-  /** Clustering method. Default: 'both' */
-  clusterBy?: ClusterType;
-}
-interface KeywordCluster {
-  clusterName: string;
-  clusterType: 'prefix' | 'intent';
-  keywords: KeywordRow[];
-  totalClicks: number;
-  totalImpressions: number;
-  avgPosition: number;
-  keywordCount: number;
-}
-interface ClusteringResult {
-  clusters: KeywordCluster[];
-  unclustered: KeywordRow[];
-}
-type ConcentrationRiskLevel = 'low' | 'medium' | 'high';
-interface ConcentrationOptions {
-  /** Number of top items to report. Default: 10 */
-  topN?: number;
-}
-interface ConcentrationItem {
-  key: string;
-  clicks: number;
-  share: number;
-}
-interface ConcentrationResult {
-  /** Gini coefficient: 0 = equal distribution, 1 = fully concentrated */
-  giniCoefficient: number;
-  /** Herfindahl-Hirschman Index: 0-10000, >2500 = highly concentrated */
-  hhi: number;
-  /** Percentage of total clicks from top N items */
-  topNConcentration: number;
-  topNItems: ConcentrationItem[];
-  totalItems: number;
-  totalClicks: number;
-  /** Risk level derived from HHI: <1500 low, 1500-2500 medium, >2500 high */
-  riskLevel: ConcentrationRiskLevel;
-}
-type DecaySortMetric = 'lostClicks' | 'declinePercent' | 'currentClicks';
-interface DecayOptions {
-  /** Minimum clicks in previous period to consider. Default: 50 */
-  minPreviousClicks?: number;
-  /** Minimum decline percentage (0-1). Default: 0.2 (20%) */
-  threshold?: number;
-  /** Metric to sort results by. Default: lostClicks */
-  sortBy?: DecaySortMetric;
-}
-interface DecaySeriesPoint {
-  week: string;
-  clicks: number;
-  impressions: number;
-}
-interface DecayResult {
-  page: string;
-  currentClicks: number;
-  previousClicks: number;
-  lostClicks: number;
-  declinePercent: number;
-  currentPosition: number;
-  previousPosition: number;
-  positionDrop: number;
-  series?: DecaySeriesPoint[];
-}
-type MoversSortMetric = 'clicks' | 'impressions' | 'clicksChange' | 'impressionsChange' | 'positionChange';
-interface MoversOptions {
-  /** Minimum change threshold to flag. Default: 0.2 (20%) */
-  changeThreshold?: number;
-  /** Minimum impressions in recent period. Default: 50 */
-  minImpressions?: number;
-  /** Metric to sort results by. Default: clicksChange */
-  sortBy?: MoversSortMetric;
-}
-interface MoverData {
-  keyword: string;
-  page: string | null;
-  recentClicks: number;
-  recentImpressions: number;
-  recentPosition: number;
-  baselineClicks: number;
-  baselineImpressions: number;
-  baselinePosition: number;
-  clicksChange: number;
-  clicksChangePercent: number;
-  impressionsChangePercent: number;
-  positionChange: number;
-}
-interface MoversResult {
-  rising: MoverData[];
-  declining: MoverData[];
-  stable: MoverData[];
-}
-interface OpportunityFactors {
-  positionScore: number;
-  impressionScore: number;
-  ctrGapScore: number;
-}
-interface OpportunityResult {
-  keyword: string;
-  page: string | null;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-  opportunityScore: number;
-  potentialClicks: number;
-  factors: OpportunityFactors;
-}
-type SeasonalityMetric = 'clicks' | 'impressions';
-interface SeasonalityOptions {
-  /** Metric to analyze for seasonality. Default: clicks */
-  metric?: SeasonalityMetric;
-}
-interface MonthlyData {
-  month: string;
-  value: number;
-  vsAverage: number;
-  isPeak: boolean;
-  isTrough: boolean;
-}
-interface SeasonalityResult {
-  hasSeasonality: boolean;
-  /** Coefficient of variation: std dev / mean. Higher = more seasonal. */
-  strength: number;
-  peakMonths: string[];
-  troughMonths: string[];
-  monthlyBreakdown: MonthlyData[];
-  insufficientData: boolean;
-}
-interface StrikingDistanceResult {
-  keyword: string;
-  page: string | null;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-  /** Estimated clicks at ~15% CTR (the average for positions 1–3). */
-  potentialClicks: number;
-}
-type StrikingDistanceSortMetric = 'clicks' | 'impressions' | 'ctr' | 'position' | 'potentialClicks';
-interface StrikingDistanceOptions {
-  /** Minimum position (inclusive). Default: 4 */
-  minPosition?: number;
-  /** Maximum position (inclusive). Default: 20 */
-  maxPosition?: number;
-  /** Minimum impressions. Default: 100 */
-  minImpressions?: number;
-  /** Maximum CTR (queries with low CTR have more potential). Default: 0.05 (5%) */
-  maxCtr?: number;
-  /** Sort metric. Default: potentialClicks */
-  sortBy?: StrikingDistanceSortMetric;
-  /** Sort order. Default: desc */
-  sortOrder?: SortOrder;
-}
-type QueryDimension = 'keywords' | 'pages' | 'dates';
-interface QueryOptions {
-  dimension?: QueryDimension;
-  limit?: number;
-}
-interface QueryResult {
-  keywords: KeywordRow[];
-  pages: PageRow[];
-  dates: DateRow[];
-}
-interface ComparisonQueryResult {
-  current: QueryResult;
-  previous: QueryResult;
-}
-interface OpportunityOptions {
-  minImpressions?: number;
-}
-declare function queryAnalyticsFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: QueryOptions): Promise<QueryResult>;
-declare function queryComparisonFromSource(source: AnalysisQuerySource, periods: ComparisonPeriod, options?: QueryOptions): Promise<ComparisonQueryResult>;
-declare function analyzeStrikingDistanceFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: StrikingDistanceOptions): Promise<StrikingDistanceResult[]>;
-declare function analyzeOpportunityFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: OpportunityOptions): Promise<OpportunityResult[]>;
-declare function analyzeBrandSegmentationFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options: BrandSegmentationOptions): Promise<BrandSegmentationResult>;
-declare function analyzePageConcentrationFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: ConcentrationOptions): Promise<ConcentrationResult>;
-declare function analyzeKeywordConcentrationFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: ConcentrationOptions): Promise<ConcentrationResult>;
-declare function analyzeClusteringFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: ClusteringOptions): Promise<ClusteringResult>;
-declare function analyzeSeasonalityFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: SeasonalityOptions): Promise<SeasonalityResult>;
-declare function analyzeDecayFromSource(source: AnalysisQuerySource, periods: ComparisonPeriod, options?: DecayOptions): Promise<DecayResult[]>;
-declare function analyzeMoversFromSource(source: AnalysisQuerySource, periods: ComparisonPeriod, options?: MoversOptions): Promise<MoversResult>;
-export { AnalyzerCapabilityError, type ComparisonQueryResult, type CompositeSourceOptions, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type QueryDimension, type QueryOptions, type QueryResult, analyzeBrandSegmentationFromSource, analyzeClusteringFromSource, analyzeDecayFromSource, analyzeFromSource, analyzeKeywordConcentrationFromSource, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentrationFromSource, analyzeSeasonalityFromSource, analyzeStrikingDistanceFromSource, createCompositeSource, createInMemoryQuerySource, queryAnalyticsFromSource, queryComparisonFromSource };
+declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): AnalysisQuerySource;
+export { type CompositeSourceOptions, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type SyncedRange, createCompositeSource, createInMemoryQuerySource };