@gscdump/analysis 0.4.0

package/dist/analyzer/index.d.mts

@@ -0,0 +1,893 @@
+import { BuilderState } from "gscdump/query";
+import { AnalysisQuerySource, FileSet, FileSet as FileSet$1 } from "@gscdump/engine/resolver";
+import { AnalysisParams, AnalysisResult } from "gscdump/contracts";
+import { Row } from "@gscdump/engine/contracts";
+/**
+ * `bayesian-ctr` — Empirical-Bayes CTR shrinkage. SQL-only colocation.
+ *
+ * Migrated from `engine-duckdb-node/src/analyzers/bayesian-ctr.ts`.
+ */
+interface BayesianCtrResult {
+  keyword: string;
+  page: string;
+  clicks: number;
+  impressions: number;
+  observedCtr: number;
+  position: number;
+  bucket: number;
+  priorAlpha: number;
+  priorBeta: number;
+  bucketPriorMean: number;
+  posteriorMean: number;
+  posteriorSd: number;
+  ciLow: number;
+  ciHigh: number;
+  shrinkageDelta: number;
+  expectedClicksDelta: number;
+  significance: number;
+  classification: 'overperforming' | 'underperforming' | 'expected';
+}
+declare const bayesianCtrAnalyzer: DefinedAnalyzer;
+/**
+ * bipartite-pagerank
+ *
+ * Personalized PageRank on the (query <-> url) bipartite graph, edge-weighted
+ * by impressions. Each power-iteration "step" is two half-steps: queries
+ * receive mass from URLs, then URLs receive mass from queries. We express
+ * the fixed-N iteration as a chain of CTEs built programmatically (bounded
+ * unroll). This sidesteps DuckDB's recursive-CTE restriction on aggregate
+ * functions over the recursive reference; the natural formulation needs
+ * SUM(prev.rank * weight) GROUP BY node_id, which recursive CTEs reject.
+ *
+ * "Hub queries" bridge many URLs with roughly-even mass distribution;
+ * "hub URLs" anchor many queries the same way. Rank is eigenvector
+ * centrality: a node is important if it links to other important nodes.
+ */
+interface BipartitePagerankNode {
+  kind: 'query' | 'url';
+  id: string;
+  rank: number;
+  bridging: number;
+  anchoring: number;
+  degree: number;
+  impressions: number;
+}
+type BipartitePagerankResult = BipartitePagerankNode;
+declare const bipartitePagerankAnalyzer: DefinedAnalyzer;
+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;
+}
+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;
+}
+interface BrandResultRow {
+  query: string;
+  page?: string;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+  segment: 'brand' | 'non-brand';
+}
+declare const brandAnalyzer: DefinedAnalyzer;
+type CannibalizationSortMetric = 'clicks' | 'impressions' | 'positionSpread' | 'pageCount';
+interface CannibalizationOptions {
+  /** Minimum impressions for a query to be considered. Default: 10 */
+  minImpressions?: number;
+  /** Maximum position spread to flag as cannibalization. Default: 10 */
+  maxPositionSpread?: number;
+  /** Minimum number of pages ranking for same query. Default: 2 */
+  minPages?: number;
+  /** Sort metric. Default: clicks */
+  sortBy?: CannibalizationSortMetric;
+  /** Sort order. Default: desc */
+  sortOrder?: SortOrder;
+}
+interface CannibalizationPage {
+  page: string;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+interface CannibalizationResult {
+  query: string;
+  pages: CannibalizationPage[];
+  totalClicks: number;
+  totalImpressions: number;
+  positionSpread: number;
+}
+interface CannibalizationCompetitor {
+  url: string;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+  share: number;
+  rank: number;
+}
+interface CannibalizationEvent {
+  keyword: string;
+  totalImpressions: number;
+  totalClicks: number;
+  competitorCount: number;
+  leaderUrl: string;
+  leaderCtr: number;
+  leaderPosition: number;
+  hhi: number;
+  fragmentation: number;
+  stolenClicks: number;
+  severity: number;
+  competitors: CannibalizationCompetitor[];
+}
+declare const cannibalizationAnalyzer: DefinedAnalyzer;
+/**
+ * `change-point` — per-(query, url) timeseries change-point detection. SQL-only.
+ *
+ * Migrated from `engine-duckdb-node/src/analyzers/change-point.ts`.
+ */
+interface ChangePointSeriesPoint {
+  date: string;
+  value: number;
+}
+interface ChangePointResult {
+  keyword: string;
+  page: string;
+  totalDays: number;
+  totalImpressions: number;
+  changeDate: string;
+  llr: number;
+  leftMean: number;
+  rightMean: number;
+  delta: number;
+  leftStddev: number;
+  rightStddev: number;
+  direction: 'improved' | 'worsened';
+  series: ChangePointSeriesPoint[];
+}
+declare const changePointAnalyzer: DefinedAnalyzer;
+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[];
+}
+declare const clusteringAnalyzer: DefinedAnalyzer;
+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 ConcentrationInput {
+  key: string;
+  clicks: 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;
+}
+declare const concentrationAnalyzer: DefinedAnalyzer;
+/**
+ * `content-velocity` — weekly new-keyword cadence. SQL-only colocation.
+ *
+ * Migrated from `engine-duckdb-node/src/analyzers/content-velocity.ts`.
+ */
+interface ContentVelocityWeek {
+  week: string;
+  newKeywords: number;
+  totalKeywords: number;
+}
+declare const contentVelocityAnalyzer: DefinedAnalyzer;
+/**
+ * `ctr-anomaly` — rolling CTR envelope per (query, page). SQL-only colocation.
+ *
+ * Migrated from `engine-duckdb-node/src/analyzers/ctr-anomaly.ts`.
+ */
+interface CtrAnomalySeriesPoint {
+  date: string;
+  ctr: number;
+  position: number;
+  impressions: number;
+  rollingCtr: number | null;
+  rollingStddev: number | null;
+  z: number;
+  breach: boolean;
+}
+interface CtrAnomalyResult {
+  keyword: string;
+  page: string;
+  breachDaysDown: number;
+  breachDaysUp: number;
+  clicksLost: number;
+  severity: number;
+  maxZ: number;
+  baselineCtr: number;
+  baselinePosition: number;
+  totalImpressions: number;
+  totalClicks: number;
+  series: CtrAnomalySeriesPoint[];
+}
+declare const ctrAnomalyAnalyzer: DefinedAnalyzer;
+/**
+ * `ctr-curve` — CTR by position bucket plus over/under-performing outliers.
+ * SQL-only colocation.
+ *
+ * Migrated from `engine-duckdb-node/src/analyzers/ctr-curve.ts`.
+ */
+interface CtrCurveBucket {
+  bucket: string;
+  avgCtr: number;
+  medianPosition: number;
+  keywordCount: number;
+  totalClicks: number;
+  totalImpressions: number;
+}
+interface CtrCurveOutlier {
+  query: string;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+  expectedCtr: number;
+  ctrDiff: number;
+}
+declare const ctrCurveAnalyzer: DefinedAnalyzer;
+/**
+ * dark-traffic — gap between page-level clicks and sum-of-keyword clicks.
+ *
+ * Reads three tables: pages (primary), keywords (summary aggregate),
+ * page_keywords (per-page attribution). Uses `extraFiles` for the latter two.
+ */
+interface DarkTrafficResult {
+  url: string;
+  totalClicks: number;
+  attributedClicks: number;
+  darkClicks: number;
+  darkPercent: number;
+  keywordCount: number;
+}
+declare const darkTrafficAnalyzer: DefinedAnalyzer;
+type DataDetailResult = Row;
+declare const dataDetailAnalyzer: DefinedAnalyzer;
+type DataQueryResult = Row;
+declare const dataQueryAnalyzer: DefinedAnalyzer;
+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 DecayInput {
+  current: PageRow[];
+  previous: PageRow[];
+}
+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[];
+}
+declare const decayAnalyzer: DefinedAnalyzer;
+/**
+ * device-gap — desktop vs mobile CTR/position delta over time.
+ */
+interface DeviceDayMetrics {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+interface DeviceGapResult {
+  date: string;
+  desktop: DeviceDayMetrics;
+  mobile: DeviceDayMetrics;
+  gaps: {
+    ctrGap: number;
+    positionGap: number;
+  };
+}
+declare const deviceGapAnalyzer: DefinedAnalyzer;
+/**
+ * intent-atlas
+ *
+ * Token-cooccurrence clustering. Tokenizes queries via regexp_split_to_array
+ * + unnest, drops stop-words and short tokens, weights tokens by impressions,
+ * then clusters each query by its top-2 highest-impression tokens (sorted +
+ * joined as the cluster key).
+ */
+interface IntentAtlasResult {
+  clusterKey: string;
+  keywordCount: number;
+  totalImpressions: number;
+  totalClicks: number;
+  ctr: number;
+  avgPosition: number;
+  keywords: Array<{
+    query: string;
+    impressions: number;
+    clicks: number;
+    position: number;
+  }>;
+}
+declare const intentAtlasAnalyzer: DefinedAnalyzer;
+/**
+ * keyword-breadth — keyword-count histogram across pages + fragile/authority
+ * classification.
+ */
+interface KeywordBreadthResult {
+  bucket: string;
+  pageCount: number;
+}
+declare const keywordBreadthAnalyzer: DefinedAnalyzer;
+/**
+ * long-tail
+ *
+ * Per-page power-law fit on log(rank) vs log(impressions) via DuckDB's
+ * REGR_SLOPE / REGR_INTERCEPT / REGR_R2 regression aggregates.
+ */
+interface LongTailResult {
+  page: string;
+  queryCount: number;
+  totalImpressions: number;
+  totalClicks: number;
+  slope: number;
+  intercept: number;
+  r2: number;
+  headImpressions: number;
+  headShare: number;
+  fingerprint: 'flat-tail' | 'balanced' | 'head-heavy';
+  points: Array<{
+    rank: number;
+    impressions: number;
+    clicks: number;
+    query: string;
+  }>;
+}
+declare const longTailAnalyzer: DefinedAnalyzer;
+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 MoversInput {
+  current: KeywordRow[];
+  previous: KeywordRow[];
+  /** If periods have different lengths, provide normalization factor (previous/current) */
+  normalizationFactor?: number;
+}
+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 MoversSeriesPoint {
+  week: string;
+  clicks: number;
+  impressions: number;
+}
+interface MoversResultRow extends MoverData {
+  direction: 'rising' | 'declining' | 'stable';
+  series?: MoversSeriesPoint[];
+}
+declare const moversAnalyzer: DefinedAnalyzer;
+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;
+}
+declare const opportunityAnalyzer: DefinedAnalyzer;
+/**
+ * position-distribution — daily count of keywords per position bucket.
+ * Matches `/api/sites/[siteId]/position-distribution.get.ts`.
+ */
+interface PositionDistributionResult {
+  date: string;
+  pos_1_3: number;
+  pos_4_10: number;
+  pos_11_20: number;
+  pos_20_plus: number;
+  total: number;
+}
+declare const positionDistributionAnalyzer: DefinedAnalyzer;
+/**
+ * position-volatility
+ *
+ * Per (page, day) compute query-level position STDDEV_POP plus day-over-day
+ * shift in weighted avg position via LAG. The resulting "volatility score"
+ * (σ + |Δpos|) surfaces pages whose SERP positioning is genuinely noisy,
+ * not just pages that rank well. Output is a pages × dates matrix for a
+ * calendar-style heatmap.
+ */
+interface PositionVolatilityDay {
+  date: string;
+  queryCount: number;
+  dayImpressions: number;
+  avgPosition: number;
+  posStddev: number;
+  bestPosition: number;
+  worstPosition: number;
+  dodShift: number;
+  volatility: number;
+}
+interface PositionVolatilityResult {
+  page: string;
+  avgVolatility: number;
+  peakVolatility: number;
+  totalImpressions: number;
+  days: PositionVolatilityDay[];
+}
+declare const positionVolatilityAnalyzer: DefinedAnalyzer;
+/**
+ * query-migration
+ *
+ * Two-period query absorption analysis. For each (page, query) pair lost in
+ * the previous period and (page, query) gained in the current period across
+ * different* pages, match via either exact string or `levenshtein()` ≤ 2
+ * edits. The matched edge represents impressions that *probably* migrated
+ * from page-A to page-B as Google reassigned the ranking URL.
+ *
+ * Output: a sankey-ready edge list grouped by (sourcePage → targetPage),
+ * weighted by absorbed impressions, with example query pairs attached.
+ */
+interface QueryMigrationExample {
+  sourceQuery: string;
+  targetQuery: string;
+  absorbed: number;
+  matchType: 'exact' | 'fuzzy';
+}
+interface QueryMigrationResult {
+  sourcePage: string;
+  targetPage: string;
+  weight: number;
+  queryCount: number;
+  exactCount: number;
+  fuzzyCount: number;
+  examples: QueryMigrationExample[];
+}
+declare const queryMigrationAnalyzer: DefinedAnalyzer;
+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;
+}
+declare const seasonalityAnalyzer: DefinedAnalyzer;
+/**
+ * stl-decompose
+ *
+ * Classical additive decomposition: observed = trend + seasonal + residual.
+ * Trend is a centered 7-day moving average; seasonal is the mean of detrended
+ * residuals per-dayofweek per-entity; residual is the leftover. Entities with
+ * a large |residual| relative to STDDEV_POP(residual) are flagged anomalous.
+ * Not true STL (no iterative LOESS), but faithful where it matters and
+ * expressible in pure DuckDB window functions.
+ */
+interface StlDecomposeSeriesPoint {
+  date: string;
+  observed: number;
+  trend: number | null;
+  seasonal: number | null;
+  residual: number | null;
+  anomaly: boolean;
+}
+interface StlDecomposeResult {
+  keyword: string;
+  page: string;
+  totalImpressions: number;
+  days: number;
+  seasonalStrength: number;
+  trendStrength: number;
+  residualAnomalies: number;
+  trendSlope: number;
+  series: StlDecomposeSeriesPoint[];
+}
+declare const stlDecomposeAnalyzer: DefinedAnalyzer;
+/**
+ * Unified `striking-distance` analyzer. Spike for the `defineAnalyzer`
+ * pattern: one file owns the SQL plan, the row plan, the typed `InputRow`
+ * contract, and the shared reducer.
+ *
+ * SQL and row plans both emit rows matching `StrikingDistanceInputRow`.
+ * Filtering (`minPosition`/`maxPosition`/`minImpressions`/`maxCtr`),
+ * derivation (`potentialClicks`), and sorting all live in the reducer, so
+ * drift between plans cannot silently change results. A SQL-side `LIMIT`
+ * push-down can be added later as an optional optimization, but the
+ * correctness contract stays with the reducer.
+ */
+/**
+ * Row shape both plans produce. Field names match GSC's native columns so
+ * the row-source path needs no rename step; the SQL plan aliases `url → page`.
+ */
+interface StrikingDistanceInputRow {
+  query: string;
+  page: string | null;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+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;
+}
+declare const strikingDistanceAnalyzer: DefinedAnalyzer;
+/**
+ * survival (Kaplan-Meier)
+ *
+ * Models "keyword survival in top-10". An episode starts the first day a
+ * (query, url) daily avg position drops to ≤10; it ends the first day
+ * position rises above 10 (simpler than the 3-day grace rule — a single bad
+ * day is rare enough at the daily-aggregate level to still give a clean
+ * tenure signal, and it avoids a windowed state machine in SQL). If the run
+ * reaches window_end - 2, the episode is censored (still alive).
+ *
+ * KM cumulative product is computed via EXP(SUM(LN(...)) OVER ...) — DuckDB
+ * has no CUMPROD, but running sums of logs with GREATEST(.., 1e-9) give the
+ * same result without any host-side math.
+ */
+interface SurvivalCurvePoint {
+  tenure: number;
+  survival: number;
+  atRisk: number;
+  events: number;
+}
+interface SurvivalResult {
+  cohort: string;
+  episodeCount: number;
+  censoringRate: number;
+  medianTenure: number;
+  curve: SurvivalCurvePoint[];
+}
+declare const survivalAnalyzer: DefinedAnalyzer;
+/**
+ * trends — weekly trajectory over a rolling window (default 28 weeks)
+ */
+type TrendCategory = 'accelerating' | 'growing' | 'steady' | 'declining' | 'cratering';
+interface TrendSeriesPoint {
+  week: string;
+  clicks: number;
+  impressions: number;
+}
+interface TrendsResult {
+  query?: string;
+  page?: string;
+  totalClicks: number;
+  totalImpressions: number;
+  weeksWithData: number;
+  slope: number;
+  growthRatio: number;
+  avgPosition: number;
+  trend: TrendCategory;
+  series: TrendSeriesPoint[];
+}
+declare const trendsAnalyzer: 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;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+declare const zeroClickAnalyzer: DefinedAnalyzer;
+interface AnalysisPeriod {
+  startDate: string;
+  endDate: string;
+}
+declare function keywordsQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
+declare function pagesQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
+declare function datesQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
+/**
+ * Capabilities a Plan may require of its host. A dispatcher matches these
+ * against a source's declared capabilities and rejects mismatches.
+ */
+type Capability = 'executeSql' | 'partitionedParquet' | 'attachedTables' | 'regex' | 'windowTotals' | 'comparisonJoin';
+interface SqlExtraQuery {
+  name: string;
+  sql: string;
+  params: unknown[];
+}
+/**
+ * SQL-native plan: SQL string + placeholders, with optional extra file sets
+ * and follow-up queries. Mirrors the existing `AnalyzerSpec` shape but
+ * renamed for clarity under the unified contract.
+ */
+interface SqlPlan {
+  kind: 'sql';
+  sql: string;
+  params: unknown[];
+  current: FileSet$1;
+  previous?: FileSet$1;
+  extraFiles?: Record<string, FileSet$1>;
+  extraQueries?: SqlExtraQuery[];
+  /** Emits direct table refs (browser-only). Dispatcher rejects for manifest path. */
+  requiresAttachedTables?: boolean;
+}
+interface TypedRowQuery<T extends Row = Row> {
+  state: BuilderState;
+  /** Optional type tag for downstream narrowing. */
+  rowType?: (row: Row) => T;
+}
+/**
+ * Row-queries plan: a named set of typed `BuilderState` queries. A portable
+ * dispatcher runs each against a source's `queryRows` and hands the row
+ * collection to `reduce`.
+ */
+interface RowQueriesPlan {
+  kind: 'rows';
+  queries: Record<string, TypedRowQuery>;
+}
+type Plan = SqlPlan | RowQueriesPlan;
+interface ReduceContext<TRow extends Row = Row> {
+  params: AnalysisParams;
+  /** Extra SQL-query results keyed by `SqlExtraQuery.name`. */
+  extras?: Record<string, TRow[]>;
+}
+/**
+ * Unified analyzer contract. `TRow` lets authors narrow from the default
+ * `Row = Record<string, unknown>` to a typed row shape (e.g. `KeywordRow`)
+ * when their reducer assumes specific columns exist — catches drift between
+ * `build` (SELECT list) and `reduce` (column access) at compile time.
+ */
+interface Analyzer<P extends AnalysisParams = AnalysisParams, R = unknown, TRow extends Row = Row> {
+  /** Stable tool id (e.g. `striking-distance`, `opportunity`). */
+  id: string;
+  /** Capabilities a host source must provide. */
+  requires: readonly Capability[];
+  /** Pure: params → plan. Snapshot-testable. */
+  build: (params: P) => Plan;
+  /** Pure: rows + context → typed result + meta. */
+  reduce: (rows: TRow[] | Record<string, TRow[]>, ctx: ReduceContext<TRow>) => {
+    results: R;
+    meta?: Record<string, unknown>;
+  };
+}
+interface SqlPlanSpec {
+  sql: string;
+  params: unknown[];
+  current: FileSet$1;
+  previous?: FileSet$1;
+  extraFiles?: Record<string, FileSet$1>;
+  extraQueries?: SqlExtraQuery[];
+  requiresAttachedTables?: boolean;
+}
+interface ReduceCtx<InputRow> {
+  /** Extra SQL-query results keyed by `SqlExtraQuery.name` (SQL path only). */
+  extras?: Record<string, InputRow[]>;
+}
+type Reducer<Params, InputRow, Result> = (rows: InputRow[] | Record<string, InputRow[]>, params: Params, ctx: ReduceCtx<InputRow>) => {
+  results: Result;
+  meta?: Record<string, unknown>;
+};
+interface DefineAnalyzerOptions<Params extends AnalysisParams, InputRow, Result> {
+  id: string;
+  /**
+   * Shared reducer used by both SQL and row paths. Use this when the
+   * post-aggregation row count is small and filter/sort/derive can live in
+   * one place. Mutually exclusive with `reduceSql` / `reduceRows`.
+   */
+  reduce?: Reducer<Params, InputRow, Result>;
+  /** SQL-only reducer. Required when `buildSql` is set without `reduce`. */
+  reduceSql?: Reducer<Params, InputRow, Result>;
+  /** Row-only reducer. Required when `buildRows` is set without `reduce`. */
+  reduceRows?: Reducer<Params, InputRow, Result>;
+  /** SQL plan builder. Omit if the analyzer has no SQL path. */
+  buildSql?: (params: Params) => SqlPlanSpec;
+  /** Row plan builder. Omit if the analyzer has no row path. */
+  buildRows?: (params: Params) => Record<string, BuilderState>;
+  /** Capabilities required by the SQL plan. Defaults to `['executeSql', 'partitionedParquet']`. */
+  sqlRequires?: readonly Capability[];
+  /** Capabilities required by the row plan. Defaults to `[]`. */
+  rowsRequires?: readonly Capability[];
+}
+interface DefinedAnalyzer {
+  id: string;
+  sql?: Analyzer;
+  rows?: Analyzer;
+}
+declare function defineAnalyzer<Params extends AnalysisParams, InputRow, Result>(opts: DefineAnalyzerOptions<Params, InputRow, Result>): DefinedAnalyzer;
+interface AnalyzerVariants {
+  sql?: Analyzer;
+  rows?: Analyzer;
+}
+interface AnalyzerRegistryInit {
+  rows?: readonly Analyzer[];
+  sql?: readonly Analyzer[];
+}
+interface AnalyzerRegistry {
+  listAnalyzerIds: () => readonly string[];
+  getAnalyzerVariants: (id: string) => AnalyzerVariants | undefined;
+  resolveAnalyzer: (id: string, sourceSupportsSql: boolean) => Analyzer | undefined;
+  listAnalyzersFor: (sourceSupportsSql: boolean) => readonly Analyzer[];
+  listAnalyzerIdsFor: (source: {
+    executeSql?: unknown;
+  }) => readonly string[];
+}
+/**
+ * Build an immutable registry from collections of row / SQL analyzers.
+ * No global state; call this once per logical use (typically at startup
+ * or per-request in a worker).
+ */
+declare function createAnalyzerRegistry(init?: AnalyzerRegistryInit): AnalyzerRegistry;
+declare class AnalyzerCapabilityError extends Error {
+  readonly tool: string;
+  readonly missing: readonly Capability[];
+  constructor(tool: string, missing: readonly Capability[]);
+}
+/**
+ * Run an analyzer against a generic `AnalysisQuerySource`. The registry is
+ * an explicit parameter — callers build one via `createAnalyzerRegistry` (or
+ * reuse `defaultAnalyzerRegistry` from the main barrel).
+ */
+declare function runAnalyzerFromSource(source: AnalysisQuerySource, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
+/**
+ * Pagination helpers shared across analyzers. SQL builders compose
+ * `paginateClause` into their tail; row reducers use `paginateInMemory`
+ * to slice already-materialized results.
+ *
+ * Sort whitelisting stays per-analyzer because each result shape has its
+ * own valid columns. `resolveSort` provides a tiny safe-cast.
+ */
+interface PaginateInput {
+  limit?: number;
+  offset?: number;
+}
+declare function clampLimit(limit: number | undefined, fallback?: number): number;
+declare function clampOffset(offset: number | undefined): number;
+/**
+ * Emits `LIMIT n` or `LIMIT n OFFSET m` literally (no placeholders) so it
+ * can be safely concatenated into the analyzer's SQL tail. Inputs are
+ * coerced and clamped — never user-controllable.
+ */
+declare function paginateClause(input: PaginateInput): string;
+/**
+ * Slice a materialized result array. Use in row reducers and in SQL
+ * reducers when SQL didn't push pagination down.
+ */
+declare function paginateInMemory<T>(rows: readonly T[], input: PaginateInput): T[];
+/**
+ * Resolve `sortBy` against an allow-list. Returns a typed key + direction
+ * suitable for ORDER BY interpolation or for indexing into a comparator
+ * map. Falls back to the analyzer's default when input is missing or
+ * unrecognized.
+ */
+declare function resolveSort<K extends string>(input: {
+  sortBy?: string;
+  sortDir?: 'asc' | 'desc';
+}, allowed: readonly K[], defaults: {
+  sortBy: K;
+  sortDir: 'asc' | 'desc';
+}): {
+  sortBy: K;
+  sortDir: 'asc' | 'desc';
+};
+declare const ROW_ANALYZERS: readonly Analyzer[];
+export { type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerVariants, 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 Capability, 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 DefineAnalyzerOptions, type DefinedAnalyzer, type DeviceGapResult, type FileSet, 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 Plan, type PositionDistributionResult, type PositionVolatilityDay, type PositionVolatilityResult, type QueryMigrationExample, type QueryMigrationResult, ROW_ANALYZERS, type ReduceContext, type RowQueriesPlan, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type StlDecomposeResult, type StlDecomposeSeriesPoint, type StrikingDistanceInputRow, type StrikingDistanceResult, type SurvivalCurvePoint, type SurvivalResult, type TrendCategory, type TrendSeriesPoint, type TrendsResult, type TypedRowQuery, type ZeroClickResult, bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, createAnalyzerRegistry, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, defineAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, keywordsQueryState, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queryMigrationAnalyzer, resolveSort, runAnalyzerFromSource, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };