@gscdump/analysis 0.4.0

package/dist/period/index.d.mts

@@ -0,0 +1,57 @@
+import { AnalysisParams } from "gscdump/contracts";
+type WindowPreset = 'last-7d' | 'last-28d' | 'last-30d' | 'last-90d' | 'last-180d' | 'last-365d' | 'mtd' | 'ytd' | 'custom';
+type ComparisonMode = 'none' | 'prev-period' | 'yoy';
+interface ResolveWindowOptions {
+  preset: WindowPreset;
+  comparison?: ComparisonMode;
+  anchor?: string;
+  start?: string;
+  end?: string;
+}
+interface ResolvedWindow {
+  start: string;
+  end: string;
+  days: number;
+  comparison?: {
+    start: string;
+    end: string;
+  };
+}
+interface AnalysisPeriod {
+  startDate: string;
+  endDate: string;
+}
+interface ComparisonPeriod {
+  current: AnalysisPeriod;
+  previous: AnalysisPeriod;
+}
+declare function defaultEndDate(): string;
+declare function defaultStartDate(): string;
+declare function periodOf(params: AnalysisParams): AnalysisPeriod;
+declare function comparisonOf(params: AnalysisParams): ComparisonPeriod;
+declare function resolveWindow(opts: ResolveWindowOptions): ResolvedWindow;
+/** Convert a ResolvedWindow into the AnalysisPeriod / ComparisonPeriod shape. */
+declare function windowToPeriod(w: ResolvedWindow): AnalysisPeriod;
+declare function windowToComparisonPeriod(w: ResolvedWindow): ComparisonPeriod | undefined;
+interface PadTimeseriesOptions<T> {
+  /** ISO date (YYYY-MM-DD), inclusive lower bound. */
+  startDate: string;
+  /** ISO date (YYYY-MM-DD), inclusive upper bound. */
+  endDate: string;
+  /**
+   * Row to insert for missing dates. Defaults to `{ clicks: 0, impressions: 0, ctr: 0, position: 0 }`.
+   * The `date` field is set automatically.
+   */
+  fill?: Omit<T, 'date'>;
+  /** Row-field that carries the ISO date. Defaults to `date`. */
+  dateKey?: string;
+}
+type DateRowShape = Record<string, unknown> & {
+  date?: unknown;
+};
+/**
+ * Pad rows so every calendar day in `[startDate, endDate]` appears at least
+ * once. Existing dates keep all their rows (grouped timeseries safe).
+ */
+declare function padTimeseries<T extends DateRowShape = DateRowShape>(rows: readonly T[], options: PadTimeseriesOptions<T>): T[];
+export { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, defaultEndDate, defaultStartDate, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod };

package/dist/period/index.mjs

@@ -0,0 +1,150 @@
+import { MS_PER_DAY, daysAgo, toIsoDate } from "gscdump";
+function defaultEndDate() {
+	return daysAgo(3);
+}
+function defaultStartDate() {
+	return daysAgo(31);
+}
+function periodOf(params) {
+	return {
+		startDate: params.startDate || defaultStartDate(),
+		endDate: params.endDate || defaultEndDate()
+	};
+}
+function comparisonOf(params) {
+	if (!params.prevStartDate || !params.prevEndDate) throw new Error(`${params.type} analysis requires prevStartDate and prevEndDate`);
+	return {
+		current: periodOf(params),
+		previous: {
+			startDate: params.prevStartDate,
+			endDate: params.prevEndDate
+		}
+	};
+}
+function parseIso(s) {
+	return /* @__PURE__ */ new Date(`${s}T00:00:00Z`);
+}
+function addDays(d, n) {
+	return new Date(d.getTime() + n * MS_PER_DAY);
+}
+function daysBetween(start, end) {
+	return Math.round((parseIso(end).getTime() - parseIso(start).getTime()) / MS_PER_DAY) + 1;
+}
+function resolveWindow(opts) {
+	const anchor = opts.anchor ? parseIso(opts.anchor) : /* @__PURE__ */ new Date();
+	const anchorIso = toIsoDate(anchor);
+	let start;
+	let end;
+	switch (opts.preset) {
+		case "last-7d":
+			end = anchorIso;
+			start = toIsoDate(addDays(anchor, -6));
+			break;
+		case "last-28d":
+			end = anchorIso;
+			start = toIsoDate(addDays(anchor, -27));
+			break;
+		case "last-30d":
+			end = anchorIso;
+			start = toIsoDate(addDays(anchor, -29));
+			break;
+		case "last-90d":
+			end = anchorIso;
+			start = toIsoDate(addDays(anchor, -89));
+			break;
+		case "last-180d":
+			end = anchorIso;
+			start = toIsoDate(addDays(anchor, -179));
+			break;
+		case "last-365d":
+			end = anchorIso;
+			start = toIsoDate(addDays(anchor, -364));
+			break;
+		case "mtd":
+			end = anchorIso;
+			start = toIsoDate(new Date(Date.UTC(anchor.getUTCFullYear(), anchor.getUTCMonth(), 1)));
+			break;
+		case "ytd":
+			end = anchorIso;
+			start = toIsoDate(new Date(Date.UTC(anchor.getUTCFullYear(), 0, 1)));
+			break;
+		case "custom":
+			if (!opts.start || !opts.end) throw new Error("resolveWindow: preset=custom requires start and end");
+			start = opts.start;
+			end = opts.end;
+			break;
+	}
+	const days = daysBetween(start, end);
+	const result = {
+		start,
+		end,
+		days
+	};
+	const mode = opts.comparison ?? "none";
+	if (mode === "prev-period") {
+		const prevEnd = toIsoDate(addDays(parseIso(start), -1));
+		result.comparison = {
+			start: toIsoDate(addDays(parseIso(prevEnd), -(days - 1))),
+			end: prevEnd
+		};
+	} else if (mode === "yoy") {
+		const prevEnd = toIsoDate(addDays(parseIso(end), -365));
+		result.comparison = {
+			start: toIsoDate(addDays(parseIso(start), -365)),
+			end: prevEnd
+		};
+	}
+	return result;
+}
+function windowToPeriod(w) {
+	return {
+		startDate: w.start,
+		endDate: w.end
+	};
+}
+function windowToComparisonPeriod(w) {
+	if (!w.comparison) return void 0;
+	return {
+		current: {
+			startDate: w.start,
+			endDate: w.end
+		},
+		previous: {
+			startDate: w.comparison.start,
+			endDate: w.comparison.end
+		}
+	};
+}
+const DEFAULT_FILL = {
+	clicks: 0,
+	impressions: 0,
+	ctr: 0,
+	position: 0
+};
+function padTimeseries(rows, options) {
+	const { startDate, endDate } = options;
+	const dateKey = options.dateKey ?? "date";
+	const fill = options.fill ?? DEFAULT_FILL;
+	const byDate = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const d = String(row[dateKey]);
+		const bucket = byDate.get(d);
+		if (bucket) bucket.push(row);
+		else byDate.set(d, [row]);
+	}
+	const result = [];
+	const start = /* @__PURE__ */ new Date(`${startDate}T00:00:00Z`);
+	const end = /* @__PURE__ */ new Date(`${endDate}T00:00:00Z`);
+	if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) throw new Error(`padTimeseries: invalid date range ${startDate}..${endDate}`);
+	for (let cursorMs = start.getTime(), endMs = end.getTime(); cursorMs <= endMs; cursorMs += MS_PER_DAY) {
+		const dateStr = toIsoDate(new Date(cursorMs));
+		const existing = byDate.get(dateStr);
+		if (existing) result.push(...existing);
+		else result.push({
+			...fill,
+			[dateKey]: dateStr
+		});
+	}
+	return result;
+}
+export { comparisonOf, defaultEndDate, defaultStartDate, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod };

package/dist/query/index.d.mts

@@ -0,0 +1,26 @@
+import { ResolverOptions } from "@gscdump/engine/resolver";
+import { Row } from "@gscdump/engine/contracts";
+import { AnalysisParams } from "gscdump/contracts";
+interface QueryAnalyzerExtraQuery {
+  name: string;
+  sql: string;
+  params: unknown[];
+}
+interface QueryAnalyzerPlan<TK extends string = string> {
+  tableKey: TK;
+  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>;
+declare function buildDataDetailPlan<TK extends string>(params: AnalysisParams, options: ResolverOptions<TK>): QueryAnalyzerPlan<TK>;
+/**
+ * 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 };

package/dist/query/index.mjs

@@ -0,0 +1,340 @@
+import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
+import { extractDateRange } from "gscdump/query";
+import { MS_PER_DAY, toIsoDate } from "gscdump";
+const DEFAULT_FILL = {
+	clicks: 0,
+	impressions: 0,
+	ctr: 0,
+	position: 0
+};
+function padTimeseries(rows, options) {
+	const { startDate, endDate } = options;
+	const dateKey = options.dateKey ?? "date";
+	const fill = options.fill ?? DEFAULT_FILL;
+	const byDate = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const d = String(row[dateKey]);
+		const bucket = byDate.get(d);
+		if (bucket) bucket.push(row);
+		else byDate.set(d, [row]);
+	}
+	const result = [];
+	const start = /* @__PURE__ */ new Date(`${startDate}T00:00:00Z`);
+	const end = /* @__PURE__ */ new Date(`${endDate}T00:00:00Z`);
+	if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) throw new Error(`padTimeseries: invalid date range ${startDate}..${endDate}`);
+	for (let cursorMs = start.getTime(), endMs = end.getTime(); cursorMs <= endMs; cursorMs += MS_PER_DAY) {
+		const dateStr = toIsoDate(new Date(cursorMs));
+		const existing = byDate.get(dateStr);
+		if (existing) result.push(...existing);
+		else result.push({
+			...fill,
+			[dateKey]: dateStr
+		});
+	}
+	return result;
+}
+function requireBuilderState(input, tool) {
+	if (!input || typeof input !== "object" || !("dimensions" in input) || !Array.isArray(input.dimensions)) throw new Error(`${tool}: params.q is required (BuilderState)`);
+	return input;
+}
+function optionalBuilderState(input, tool, key) {
+	if (input == null) return null;
+	if (typeof input !== "object" || !("dimensions" in input) || !Array.isArray(input.dimensions)) throw new Error(`${tool}: params.${key} must be a BuilderState`);
+	return input;
+}
+const NUMERIC_METRIC_COLS = [
+	"clicks",
+	"impressions",
+	"ctr",
+	"position",
+	"prevClicks",
+	"prevImpressions",
+	"prevCtr",
+	"prevPosition",
+	"variantCount",
+	"totalCount"
+];
+function coerceNumericCols(row) {
+	const out = { ...row };
+	for (const col of NUMERIC_METRIC_COLS) if (col in out && out[col] != null) out[col] = Number(out[col]);
+	return out;
+}
+function shapeDataQuery(rows, extras, opts) {
+	let totalCount;
+	let cleaned;
+	if (opts.hasPrev) {
+		cleaned = rows.map(coerceNumericCols);
+		totalCount = Number((extras?.count?.[0])?.total ?? cleaned.length);
+	} else {
+		const first = rows[0];
+		totalCount = Number(first?.totalCount ?? 0);
+		cleaned = rows.map((raw) => {
+			const { totalCount: _tc, totalClicks: _tclk, totalImpressions: _timp, totalCtr: _tctr, totalPosition: _tpos, sum_position: _sp, ...rest } = raw;
+			return coerceNumericCols(rest);
+		});
+	}
+	const totalsRow = extras?.totals?.[0] ?? {};
+	const totals = {
+		clicks: Number(totalsRow.clicks ?? 0),
+		impressions: Number(totalsRow.impressions ?? 0),
+		ctr: Number(totalsRow.ctr ?? 0),
+		position: Number(totalsRow.position ?? 0)
+	};
+	const extrasResults = [];
+	if (extras?.canonicalExtras) extrasResults.push({
+		key: "canonicalExtras",
+		results: extras.canonicalExtras
+	});
+	return {
+		results: mergeExtras(cleaned, extrasResults),
+		meta: {
+			totalCount,
+			totals
+		}
+	};
+}
+function buildDataQueryPlan(params, options) {
+	const state = requireBuilderState(params.q, "data-query");
+	if (state.dimensions.includes("date")) throw new Error("data-query: date dimension not supported; use data-detail");
+	const prev = optionalBuilderState(params.qc, "data-query", "qc");
+	const totals = buildTotalsSql(state, options);
+	const extras = buildExtrasQueries(state, options);
+	const extraQueries = [{
+		name: "totals",
+		sql: totals.sql,
+		params: totals.params
+	}, ...extras.map((extra) => ({
+		name: extra.key,
+		sql: extra.sql,
+		params: extra.params
+	}))];
+	const tableKey = options.adapter.inferTable(state.dimensions);
+	if (prev) {
+		const comparison = resolveComparisonSQL(state, prev, options, params.comparisonFilter);
+		extraQueries.push({
+			name: "count",
+			sql: comparison.countSql,
+			params: comparison.countParams
+		});
+		return {
+			tableKey,
+			sql: comparison.sql,
+			params: comparison.params,
+			extraQueries,
+			shape: (rows, _params, resolvedExtras) => shapeDataQuery(rows, resolvedExtras, { hasPrev: true })
+		};
+	}
+	const optimized = resolveToSQLOptimized(state, options);
+	return {
+		tableKey,
+		sql: optimized.sql,
+		params: optimized.params,
+		extraQueries,
+		shape: (rows, _params, resolvedExtras) => shapeDataQuery(rows, resolvedExtras, { hasPrev: false })
+	};
+}
+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 prev = optionalBuilderState(params.qc, "data-detail", "qc");
+	const extraQueries = [{
+		name: "totals",
+		sql: totals.sql,
+		params: totals.params
+	}];
+	if (prev) {
+		const previousTotals = buildTotalsSql(prev, options);
+		extraQueries.push({
+			name: "prevTotals",
+			sql: previousTotals.sql,
+			params: previousTotals.params
+		});
+	}
+	const tableKey = options.adapter.inferTable(state.dimensions);
+	const { startDate: rangeStart, endDate: rangeEnd } = extractDateRange(state.filter);
+	return {
+		tableKey,
+		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
+			};
+		}
+	};
+}
+const SYNONYMS = {
+	checker: "validator",
+	tester: "validator",
+	verifier: "validator",
+	verify: "validate",
+	check: "validate",
+	test: "validate",
+	checking: "validate",
+	testing: "validate",
+	creator: "generator",
+	builder: "generator",
+	maker: "generator",
+	create: "generate",
+	build: "generate",
+	make: "generate",
+	lookup: "search",
+	finder: "search",
+	find: "search",
+	online: "",
+	free: ""
+};
+const NO_STRIP_S = new Set([
+	"css",
+	"js",
+	"ts",
+	"os",
+	"as",
+	"is",
+	"us",
+	"has",
+	"was",
+	"its",
+	"this",
+	"yes",
+	"no",
+	"bus",
+	"gas",
+	"dns",
+	"rss",
+	"sms",
+	"gps",
+	"aws",
+	"sas",
+	"cms",
+	"ios",
+	"less",
+	"loss",
+	"miss",
+	"pass",
+	"class",
+	"access",
+	"process",
+	"express",
+	"address",
+	"cross",
+	"press",
+	"stress",
+	"progress",
+	"success",
+	"business",
+	"wordpress",
+	"status",
+	"radius",
+	"nexus",
+	"focus",
+	"bonus",
+	"campus",
+	"census",
+	"corpus",
+	"nucleus",
+	"stimulus",
+	"terminus",
+	"versus",
+	"virus",
+	"surplus",
+	"cactus",
+	"analysis",
+	"basis",
+	"thesis",
+	"crisis",
+	"axis",
+	"genesis",
+	"synopsis",
+	"diagnosis",
+	"emphasis",
+	"hypothesis",
+	"synthesis",
+	"parenthesis",
+	"redis",
+	"apis",
+	"chaos",
+	"demos",
+	"logos",
+	"photos",
+	"videos",
+	"nuxtjs",
+	"nextjs",
+	"nodejs",
+	"reactjs",
+	"vuejs",
+	"angularjs",
+	"expressjs",
+	"nestjs",
+	"threejs",
+	"alpinejs",
+	"solidjs",
+	"sveltejs",
+	"dejs",
+	"bunjs",
+	"denojs",
+	"canvas",
+	"atlas",
+	"alias",
+	"bias",
+	"perhaps",
+	"whereas",
+	"kubernetes",
+	"sass",
+	"postgres",
+	"always",
+	"across",
+	"previous",
+	"various",
+	"serious",
+	"famous",
+	"anonymous",
+	"continuous",
+	"dangerous",
+	"generous",
+	"obvious",
+	"numerous",
+	"curious",
+	"nervous",
+	"conscious"
+]);
+function depluralize(token) {
+	if (token.length <= 3) return token;
+	if (NO_STRIP_S.has(token)) return token;
+	if (token.endsWith("ies") && token.length > 4) return `${token.slice(0, -3)}y`;
+	if (token.endsWith("ses") && token.length > 4) return token.slice(0, -1);
+	if (token.endsWith("shes") || token.endsWith("ches") || token.endsWith("xes") || token.endsWith("zes")) return token.slice(0, -2);
+	if (token.endsWith("s") && !token.endsWith("ss")) return token.slice(0, -1);
+	return token;
+}
+const SEPARATOR_RE = /[-_/.@#:+]+/g;
+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 };

package/dist/semantic/index.d.mts

@@ -0,0 +1,70 @@
+import { AnalysisQuerySource } from "@gscdump/engine/resolver";
+interface ContentGapResult {
+  query: string;
+  impressions: number;
+  clicks: number;
+  avgPosition: number;
+  currentUrl: string;
+  currentSimilarity: number;
+  suggestedUrl: string;
+  suggestedSimilarity: number;
+  alternatives: Array<{
+    url: string;
+    similarity: number;
+  }>;
+  divergence: number;
+  impact: number;
+}
+interface ContentGapProgress {
+  phase: 'idle' | 'loading-model' | 'fetching-data' | 'embedding-queries' | 'embedding-urls' | 'computing-gaps' | 'done' | 'error';
+  message: string;
+  done?: number;
+  total?: number;
+  modelMs?: number;
+  sqlMs?: number;
+  embedMs?: number;
+  computeMs?: number;
+}
+interface ContentGapOptions {
+  maxQueries?: number;
+  maxUrls?: number;
+  minImpressions?: number;
+  minDivergence?: number;
+  device?: 'webgpu' | 'wasm';
+  onProgress?: (progress: ContentGapProgress) => void;
+}
+/**
+ * Content-gap requires a source with a raw-SQL escape hatch. The analyzer's
+ * query shape (CTEs + window functions against `main.page_keywords`) isn't
+ * expressible as a {@link BuilderState}, so it bypasses `queryRows` and
+ * goes directly through `source.executeSql`.
+ */
+declare class ContentGapSourceUnsupportedError extends Error {
+  constructor(kind: string);
+}
+interface ContentGapAnalysis {
+  results: ContentGapResult[];
+  meta: {
+    modelMs: number;
+    sqlMs: number;
+    embedMs: number;
+    computeMs: number;
+    cacheHits: number;
+    totalInputs: number;
+    device: 'webgpu' | 'wasm';
+    modelId: string;
+  };
+}
+interface QueryCandidate {
+  query: string;
+  impressions: number;
+  clicks: number;
+  avgPosition: number;
+  currentUrl: string;
+}
+declare function normalizeUrl(u: string): string;
+declare function deriveUrlText(url: string): string;
+declare function cosineNormalized(a: Float32Array, b: Float32Array): number;
+declare function rankContentGaps(queries: QueryCandidate[], urls: string[], queryEmbeddings: Float32Array[], urlEmbeddings: Float32Array[], minDivergence: number): ContentGapResult[];
+declare function analyzeContentGap(source: AnalysisQuerySource, opts?: ContentGapOptions): Promise<ContentGapAnalysis>;
+export { type ContentGapAnalysis, type ContentGapOptions, type ContentGapProgress, type ContentGapResult, ContentGapSourceUnsupportedError, analyzeContentGap, cosineNormalized, deriveUrlText, normalizeUrl, rankContentGaps };