@gscdump/analysis 1.3.2 → 1.4.1

package/dist/query/analyzers.mjs

@@ -0,0 +1,301 @@
+import { padTimeseries } from "@gscdump/engine/period";
+import { extractDateRange } from "gscdump/query";
+import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
+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;
+	let totals;
+	if (opts.hasPrev) {
+		cleaned = rows.map(coerceNumericCols);
+		totalCount = Number((extras?.count?.[0])?.total ?? cleaned.length);
+		const totalsRow = extras?.totals?.[0] ?? {};
+		totals = {
+			clicks: Number(totalsRow.clicks ?? 0),
+			impressions: Number(totalsRow.impressions ?? 0),
+			ctr: Number(totalsRow.ctr ?? 0),
+			position: Number(totalsRow.position ?? 0)
+		};
+	} else {
+		const first = rows[0];
+		totalCount = Number(first?.totalCount ?? 0);
+		totals = {
+			clicks: Number(first?.totalClicks ?? 0),
+			impressions: Number(first?.totalImpressions ?? 0),
+			ctr: Number(first?.totalCtr ?? 0),
+			position: Number(first?.totalPosition ?? 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 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 extraQueries = [...buildExtrasQueries(state, options).map((extra) => ({
+		name: extra.key,
+		sql: extra.sql,
+		params: extra.params
+	}))];
+	const tableKey = options.adapter.inferTable(state.dimensions);
+	if (prev) {
+		const totals = buildTotalsSql(state, options);
+		const comparison = resolveComparisonSQL(state, prev, options, params.comparisonFilter);
+		extraQueries.unshift({
+			name: "totals",
+			sql: totals.sql,
+			params: totals.params
+		});
+		extraQueries.push({
+			name: "count",
+			sql: comparison.countSql,
+			params: comparison.countParams
+		});
+		return {
+			tableKey,
+			sql: comparison.sql,
+			params: comparison.params,
+			extraQueries
+		};
+	}
+	const optimized = resolveToSQLOptimized(state, options);
+	return {
+		tableKey,
+		sql: optimized.sql,
+		params: optimized.params,
+		extraQueries
+	};
+}
+function totalsState(state) {
+	return {
+		...state,
+		dimensions: [],
+		orderBy: void 0,
+		rowLimit: 1
+	};
+}
+function readTotals(row) {
+	return {
+		clicks: Number(row?.clicks ?? 0),
+		impressions: Number(row?.impressions ?? 0),
+		ctr: Number(row?.ctr ?? 0),
+		position: Number(row?.position ?? 0)
+	};
+}
+function buildDataQueryRows(params) {
+	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 queries = {
+		main: state,
+		totals: totalsState(state)
+	};
+	const prev = optionalBuilderState(params.qc, "data-query", "qc");
+	if (prev) {
+		queries.prevMain = prev;
+		queries.prevTotals = totalsState(prev);
+	}
+	return queries;
+}
+function shapeDataQueryRowResults(rowMap, params) {
+	const main = (rowMap.main ?? []).map((r) => coerceNumericCols(r));
+	const totals = readTotals(rowMap.totals?.[0]);
+	if (params.qc == null) return {
+		results: main,
+		meta: {
+			totalCount: main.length,
+			totals
+		}
+	};
+	const state = requireBuilderState(params.q, "data-query");
+	const dims = state.dimensions;
+	const keyOf = (row) => dims.map((d) => String(row[d] ?? "")).join("");
+	const prevByKey = /* @__PURE__ */ new Map();
+	for (const r of rowMap.prevMain ?? []) prevByKey.set(keyOf(r), r);
+	const filter = params.comparisonFilter;
+	const merged = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const cur of main) {
+		const key = keyOf(cur);
+		seen.add(key);
+		const prev = prevByKey.get(key);
+		const row = {
+			...cur,
+			prevClicks: Number(prev?.clicks ?? 0),
+			prevImpressions: Number(prev?.impressions ?? 0),
+			prevCtr: Number(prev?.ctr ?? 0),
+			prevPosition: Number(prev?.position ?? 0)
+		};
+		if (passesComparisonFilter(filter, {
+			isNew: !prev,
+			isLost: false,
+			clicksChange: Number(cur.clicks ?? 0) - Number(prev?.clicks ?? 0)
+		})) merged.push(row);
+	}
+	for (const prev of rowMap.prevMain ?? []) {
+		const p = prev;
+		const key = keyOf(p);
+		if (seen.has(key)) continue;
+		const row = {
+			...p,
+			clicks: 0,
+			impressions: 0,
+			ctr: 0,
+			position: 0,
+			prevClicks: Number(p.clicks ?? 0),
+			prevImpressions: Number(p.impressions ?? 0),
+			prevCtr: Number(p.ctr ?? 0),
+			prevPosition: Number(p.position ?? 0)
+		};
+		if (passesComparisonFilter(filter, {
+			isNew: false,
+			isLost: true,
+			clicksChange: -Number(p.clicks ?? 0)
+		})) merged.push(row);
+	}
+	if (state.orderBy) {
+		const { column, dir } = state.orderBy;
+		merged.sort((a, b) => {
+			const av = Number(a[column]) || 0;
+			const bv = Number(b[column]) || 0;
+			return dir === "asc" ? av - bv : bv - av;
+		});
+	}
+	return {
+		results: merged.map((r) => coerceNumericCols(r)),
+		meta: {
+			totalCount: merged.length,
+			totals
+		}
+	};
+}
+function passesComparisonFilter(filter, ctx) {
+	switch (filter) {
+		case "new": return ctx.isNew;
+		case "lost": return ctx.isLost;
+		case "improving": return ctx.clicksChange > 0;
+		case "declining": return ctx.clicksChange < 0;
+		default: return true;
+	}
+}
+function buildDataDetailRows(params) {
+	const state = requireBuilderState(params.q, "data-detail");
+	if (!state.dimensions.includes("date")) throw new Error("data-detail: `date` dimension is required");
+	const queries = {
+		main: state,
+		totals: totalsState(state)
+	};
+	const prev = optionalBuilderState(params.qc, "data-detail", "qc");
+	if (prev) queries.prevTotals = totalsState(prev);
+	return queries;
+}
+function shapeDataDetailRowResults(rowMap, params) {
+	const { startDate, endDate } = extractDateRange(requireBuilderState(params.q, "data-detail").filter);
+	const coerced = (rowMap.main ?? []).map((r) => coerceNumericCols(r));
+	const daily = startDate && endDate ? padTimeseries(coerced, {
+		startDate,
+		endDate
+	}) : coerced;
+	const meta = { totals: readTotals(rowMap.totals?.[0]) };
+	if (rowMap.prevTotals) meta.previousTotals = readTotals(rowMap.prevTotals[0]);
+	return {
+		results: daily,
+		meta
+	};
+}
+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");
+	const main = resolveToSQLOptimized(state, options);
+	const prev = optionalBuilderState(params.qc, "data-detail", "qc");
+	const extraQueries = [];
+	if (prev) {
+		const previousTotals = buildTotalsSql(prev, options);
+		extraQueries.push({
+			name: "prevTotals",
+			sql: previousTotals.sql,
+			params: previousTotals.params
+		});
+	}
+	return {
+		tableKey: options.adapter.inferTable(state.dimensions),
+		sql: main.sql,
+		params: main.params,
+		extraQueries
+	};
+}
+function shapeDataDetailRows(rows, params, extras) {
+	const { startDate: rangeStart, endDate: rangeEnd } = extractDateRange(requireBuilderState(params.q, "data-detail").filter);
+	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 meta = { totals };
+	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
+	};
+}
+export { buildDataDetailPlan, buildDataDetailRows, buildDataQueryPlan, buildDataQueryRows, shapeDataDetailRowResults, shapeDataDetailRows, shapeDataQueryRowResults, shapeDataQueryRows };

package/dist/query/index.mjs

@@ -0,0 +1,4 @@
+import { buildDataDetailPlan, buildDataDetailRows, buildDataQueryPlan, buildDataQueryRows, shapeDataDetailRowResults, shapeDataDetailRows, shapeDataQueryRowResults, shapeDataQueryRows } from "./analyzers.mjs";
+import "./intent.mjs";
+import "./normalize.mjs";
+export { buildDataDetailPlan, buildDataDetailRows, buildDataQueryPlan, buildDataQueryRows, shapeDataDetailRowResults, shapeDataDetailRows, shapeDataQueryRowResults, shapeDataQueryRows };

package/dist/query/intent.d.mts

@@ -0,0 +1,20 @@
+declare const INTENT_CLASSIFIER_VERSION = 1;
+type SearchIntent = 'transactional' | 'commercial' | 'informational' | 'unknown';
+interface IntentClassification {
+  /** Primary intent, by priority transactional > commercial > informational. */
+  intent: SearchIntent;
+  /** Procedural sub-signal of informational ("how to …"). */
+  howTo: boolean;
+  /** Matched cue tokens/phrases, for explainability + debugging. */
+  signals: readonly string[];
+}
+declare const SEARCH_INTENT_CODE: Record<SearchIntent, number>;
+/** Pack a classification into one small int for cheap dimension storage. */
+declare function encodeIntent(c: Pick<IntentClassification, 'intent' | 'howTo'>): number;
+/**
+ * Classify the search intent of a raw query from lexical cues. Deterministic;
+ * version it (`INTENT_CLASSIFIER_VERSION`) and bump on any rule change so a
+ * materialized `intent` can detect staleness, like the canonical normalizer.
+ */
+declare function classifyQueryIntent(query: string): IntentClassification;
+export { INTENT_CLASSIFIER_VERSION, IntentClassification, SEARCH_INTENT_CODE, SearchIntent, classifyQueryIntent, encodeIntent };

package/dist/query/intent.mjs

@@ -0,0 +1,139 @@
+const INTENT_CLASSIFIER_VERSION = 1;
+const SEARCH_INTENT_CODE = {
+	unknown: 0,
+	informational: 1,
+	commercial: 2,
+	transactional: 3
+};
+const HOWTO_BIT = 4;
+function encodeIntent(c) {
+	return SEARCH_INTENT_CODE[c.intent] | (c.howTo ? HOWTO_BIT : 0);
+}
+const INFORMATIONAL = /* @__PURE__ */ new Set([
+	"how",
+	"what",
+	"why",
+	"when",
+	"where",
+	"who",
+	"which",
+	"whose",
+	"whom",
+	"guide",
+	"tutorial",
+	"example",
+	"examples",
+	"meaning",
+	"definition",
+	"define",
+	"explained",
+	"explain",
+	"tip",
+	"idea",
+	"learn",
+	"basics",
+	"intro",
+	"introduction",
+	"overview",
+	"cheatsheet",
+	"documentation",
+	"docs",
+	"faq"
+]);
+const COMMERCIAL = /* @__PURE__ */ new Set([
+	"best",
+	"top",
+	"vs",
+	"versus",
+	"review",
+	"comparison",
+	"compare",
+	"alternative",
+	"alternatives",
+	"cheapest",
+	"recommended",
+	"popular"
+]);
+const TRANSACTIONAL = /* @__PURE__ */ new Set([
+	"buy",
+	"price",
+	"pricing",
+	"cost",
+	"cheap",
+	"coupon",
+	"deal",
+	"discount",
+	"order",
+	"purchase",
+	"download",
+	"subscribe",
+	"subscription",
+	"signup",
+	"trial",
+	"demo",
+	"install",
+	"free",
+	"sale",
+	"quote",
+	"checkout",
+	"cart"
+]);
+const PHRASE_CUES = [
+	{
+		re: /\bfor sale\b/,
+		intent: "transactional"
+	},
+	{
+		re: /\bsign up\b/,
+		intent: "transactional"
+	},
+	{
+		re: /\bnear me\b/,
+		intent: "transactional"
+	},
+	{
+		re: /\bhow much\b/,
+		intent: "transactional"
+	}
+];
+const SEPARATOR_RE = /[-_/.@#:+]+/g;
+const WHITESPACE_RE = /\s+/g;
+const DIACRITICS_RE = /\p{Diacritic}/gu;
+function tokenize(query) {
+	let index = 0;
+	while (index < query.length && query.charCodeAt(index) <= 127) index++;
+	const text = (index === query.length ? query : query.normalize("NFKD").replace(DIACRITICS_RE, "")).toLowerCase().replace(SEPARATOR_RE, " ").replace(WHITESPACE_RE, " ").trim();
+	return {
+		text,
+		tokens: text.length === 0 ? [] : text.split(" ")
+	};
+}
+function classifyQueryIntent(query) {
+	const { text, tokens } = tokenize(query);
+	const signals = [];
+	let transactional = false;
+	let commercial = false;
+	let informational = false;
+	for (const t of tokens) if (TRANSACTIONAL.has(t)) {
+		transactional = true;
+		signals.push(t);
+	} else if (COMMERCIAL.has(t)) {
+		commercial = true;
+		signals.push(t);
+	} else if (INFORMATIONAL.has(t)) {
+		informational = true;
+		signals.push(t);
+	}
+	for (const { re, intent } of PHRASE_CUES) if (re.test(text)) {
+		signals.push(re.source);
+		if (intent === "transactional") transactional = true;
+	}
+	const howTo = /\bhow to\b/.test(text);
+	if (howTo) informational = true;
+	return {
+		intent: transactional ? "transactional" : commercial ? "commercial" : informational ? "informational" : "unknown",
+		howTo,
+		signals
+	};
+}
+export { INTENT_CLASSIFIER_VERSION, SEARCH_INTENT_CODE, classifyQueryIntent, encodeIntent };

package/dist/query/normalize.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Algorithm version. Bump on ANY behaviour change (synonyms, depluralize,
+ * folding) so downstream stores can record which version produced a
+ * `query_canonical` and detect/repair staleness on a rule change instead of
+ * silently mixing old and new keys. v1 = the original ASCII heuristic;
+ * v2 adds Unicode folding, the empty-canonical guard, and `pluralize`-based
+ * singularization.
+ */
+declare const NORMALIZER_VERSION = 2;
+/**
+ * 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 { NORMALIZER_VERSION, normalizeQuery };

package/dist/query/normalize.mjs

@@ -0,0 +1,204 @@
+import pluralize from "pluralize";
+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 = /* @__PURE__ */ 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"
+]);
+const DEPLURALIZED_CACHE_MAX = 4096;
+const depluralizedCache = /* @__PURE__ */ new Map();
+function depluralize(token) {
+	if (token.length <= 3 || NO_STRIP_S.has(token) || token.endsWith("sis")) return token;
+	const last = token.charCodeAt(token.length - 1);
+	if (last < 97 || last > 122) return token;
+	const cached = depluralizedCache.get(token);
+	if (cached !== void 0) return cached;
+	const singular = pluralize.singular(token);
+	if (depluralizedCache.size >= DEPLURALIZED_CACHE_MAX) depluralizedCache.clear();
+	depluralizedCache.set(token, singular);
+	return singular;
+}
+const SEPARATOR_RE = /[-_/.@#:+]+/g;
+const WHITESPACE_RE = /\s+/g;
+const DIACRITICS_RE = /\p{Diacritic}/gu;
+const NORMALIZER_VERSION = 2;
+function foldUnicode(s) {
+	let index = 0;
+	while (index < s.length && s.charCodeAt(index) <= 127) index++;
+	if (index === s.length) return s;
+	return s.normalize("NFKD").replace(DIACRITICS_RE, "");
+}
+const DIRECTIONAL_CONNECTORS = /* @__PURE__ */ new Set([
+	"to",
+	"into",
+	">",
+	"→"
+]);
+const NON_DIRECTIONAL_BEFORE = /* @__PURE__ */ new Set([
+	"how",
+	"what",
+	"why",
+	"when",
+	"where",
+	"who",
+	"which",
+	"guide",
+	"way",
+	"tip",
+	"intro",
+	"introduction",
+	"learn",
+	"tutorial",
+	"step",
+	"reason",
+	"idea",
+	"example",
+	"benefit",
+	"need"
+]);
+function isOrderSensitive(tokens) {
+	for (let i = 1; i < tokens.length - 1; i++) if (DIRECTIONAL_CONNECTORS.has(tokens[i]) && !NON_DIRECTIONAL_BEFORE.has(tokens[i - 1])) return true;
+	return false;
+}
+function normalizeQuery(query) {
+	const normalized = foldUnicode(query).toLowerCase().replace(SEPARATOR_RE, " ").replace(WHITESPACE_RE, " ").trim();
+	if (normalized.length === 0) return "";
+	const cleaned = normalized.split(" ");
+	const mapped = [];
+	for (const token of cleaned) {
+		const synonym = SYNONYMS[token] ?? token;
+		if (synonym) mapped.push(depluralize(synonym));
+	}
+	const tokens = mapped.length > 0 ? mapped : cleaned.map(depluralize);
+	return (isOrderSensitive(tokens) ? tokens : tokens.sort()).join(" ");
+}
+export { NORMALIZER_VERSION, normalizeQuery };

package/dist/report/format.d.mts

@@ -0,0 +1,7 @@
+import { ReportResult } from "@gscdump/engine/report";
+interface FormatReportOptions {
+  /** Cap findings rendered per section. Defaults to all (already bounded by report). */
+  maxFindingsPerSection?: number;
+}
+declare function formatReport(report: ReportResult, opts?: FormatReportOptions): string;
+export { FormatReportOptions, formatReport };