@gscdump/analysis 0.30.0 → 0.31.0

package/dist/index.d.mts

@@ -440,6 +440,39 @@ declare function formatAnalysisError(error: AnalysisError): string;
  * continue to match.
  */
 declare function analysisErrorToException(error: AnalysisError): Error;
+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;
+/** Inverse of {@link encodeIntent}. */
+declare function decodeIntent(code: number): {
+  intent: SearchIntent;
+  howTo: boolean;
+};
+/**
+ * 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;
+/**
+ * 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)`.
@@ -567,4 +600,4 @@ interface InMemoryQuerySourceOptions {
 }
 declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): AnalysisQuerySource$1;
 declare const SQL_ANALYZERS: readonly Analyzer$1[];
-export { type ActionPriorityResult, type ActionPrioritySourceState, type ActionPrioritySourceStatus, type ActionSource, type AnalysisError, type AnalysisErrorKind, type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, type AnalysisSourceKind, type AnalysisTool, type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerRunner, type AnalyzerVariants, type BaseMetrics, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type BrowserAnalyzeOptions, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type CompositeSourceOptions, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, DEFAULT_PRIORITY_SOURCES, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefineReportOptions, type DefinedAnalyzer, type DefinedReport, type DryRunReportResult, ENGINE_QUERY_CAPABILITIES, type Effort, type EngineQuerySourceOptions, type ExecuteSqlOptions, type FileSet, type FormatReportOptions, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type KeywordCluster, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, type OpportunityResult, type PadTimeseriesOptions, type PageRow, type Plan, type PriorityAction, type QueriesRow, type QueryPageRow, type QueryRow, REPORTS, ROW_ANALYZERS, type ReduceContext, type ReduceCtx, type Reducer, type ReportAction, type ReportContext, type ReportFinding, type ReportPlanStep, type ReportResult, type ReportSection, type RequiredCapability, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, type RunReportOptions, SQL_ANALYZERS, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SitemapDelta, type SitemapHealthDiff, type SitemapHealthInput, type SitemapHealthRow, type SitemapHealthTotals, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type StrikingDistanceInputRow, type StrikingDistanceResult, type TypedQuery, type TypedRowQuery, type WindowPreset, type ZeroClickResult, analysisErrorToException, analysisErrors, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzePageConcentration, analyzeSeasonality, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, diffSitemapHealth, dryRunReport, formatAnalysisError, formatReport, isAnalysisError, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, runReportResult, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };
+export { type ActionPriorityResult, type ActionPrioritySourceState, type ActionPrioritySourceStatus, type ActionSource, type AnalysisError, type AnalysisErrorKind, type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, type AnalysisSourceKind, type AnalysisTool, type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerRunner, type AnalyzerVariants, type BaseMetrics, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type BrowserAnalyzeOptions, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type CompositeSourceOptions, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, DEFAULT_PRIORITY_SOURCES, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefineReportOptions, type DefinedAnalyzer, type DefinedReport, type DryRunReportResult, ENGINE_QUERY_CAPABILITIES, type Effort, type EngineQuerySourceOptions, type ExecuteSqlOptions, type FileSet, type FormatReportOptions, INTENT_CLASSIFIER_VERSION, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type IntentClassification, type KeywordCluster, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, NORMALIZER_VERSION, type OpportunityResult, type PadTimeseriesOptions, type PageRow, type Plan, type PriorityAction, type QueriesRow, type QueryPageRow, type QueryRow, REPORTS, ROW_ANALYZERS, type ReduceContext, type ReduceCtx, type Reducer, type ReportAction, type ReportContext, type ReportFinding, type ReportPlanStep, type ReportResult, type ReportSection, type RequiredCapability, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, type RunReportOptions, SEARCH_INTENT_CODE, SQL_ANALYZERS, type SearchIntent, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SitemapDelta, type SitemapHealthDiff, type SitemapHealthInput, type SitemapHealthRow, type SitemapHealthTotals, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type StrikingDistanceInputRow, type StrikingDistanceResult, type TypedQuery, type TypedRowQuery, type WindowPreset, type ZeroClickResult, analysisErrorToException, analysisErrors, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzePageConcentration, analyzeSeasonality, classifyQueryIntent, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, decodeIntent, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, diffSitemapHealth, dryRunReport, encodeIntent, formatAnalysisError, formatReport, isAnalysisError, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, runReportResult, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };

package/dist/index.mjs

@@ -7,6 +7,7 @@ import { err, ok, unwrapResult } from "gscdump/result";
 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 pluralize from "pluralize";
 import { ENGINE_QUERY_CAPABILITIES, createAttachedTableSource, createEngineQuerySource, queryComparisonRows, queryRows, rewriteForTableSource, runAnalyzerWithEngine, typedQuery } from "@gscdump/engine/source";
 import { computeInputHash, createReportRegistry, defineReport } from "@gscdump/engine/report";
 import { canProxyToGsc } from "@gscdump/engine-gsc-api";
@@ -1370,7 +1371,7 @@ const INTENT_PREFIXES = [
 	"free",
 	"near me"
 ];
-const WHITESPACE_RE$1 = /\s+/;
+const WHITESPACE_RE$2 = /\s+/;
 function str$18(v) {
 	return v == null ? "" : String(v);
 }
@@ -1388,7 +1389,7 @@ function extractIntentPrefix(keyword) {
 	return null;
 }
 function extractWordPrefix(keyword, wordCount = 2) {
-	const words = keyword.toLowerCase().split(WHITESPACE_RE$1).filter(Boolean);
+	const words = keyword.toLowerCase().split(WHITESPACE_RE$2).filter(Boolean);
 	if (words.length < wordCount + 1) return null;
 	return words.slice(0, wordCount).join(" ");
 }
@@ -2600,6 +2601,154 @@ function shapeDataDetailRows(rows, params, extras) {
 		meta
 	};
 }
+const INTENT_CLASSIFIER_VERSION = 1;
+const SEARCH_INTENT_CODE = {
+	unknown: 0,
+	informational: 1,
+	commercial: 2,
+	transactional: 3
+};
+const INTENT_BY_CODE = [
+	"unknown",
+	"informational",
+	"commercial",
+	"transactional"
+];
+const HOWTO_BIT = 4;
+function encodeIntent(c) {
+	return SEARCH_INTENT_CODE[c.intent] | (c.howTo ? HOWTO_BIT : 0);
+}
+function decodeIntent(code) {
+	return {
+		intent: INTENT_BY_CODE[code & 3] ?? "unknown",
+		howTo: (code & 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$1 = /[-_/.@#:+]+/g;
+const WHITESPACE_RE$1 = /\s+/g;
+const DIACRITICS_RE$1 = /\p{Diacritic}/gu;
+function tokenize(query) {
+	const text = query.normalize("NFKD").replace(DIACRITICS_RE$1, "").toLowerCase().replace(SEPARATOR_RE$1, " ").replace(WHITESPACE_RE$1, " ").trim();
+	return {
+		text,
+		tokens: text.split(" ").filter(Boolean)
+	};
+}
+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
+	};
+}
 const SYNONYMS = {
 	checker: "validator",
 	tester: "validator",
@@ -2736,18 +2885,53 @@ const NO_STRIP_S = /* @__PURE__ */ new Set([
 	"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;
+	if (token.length <= 3 || NO_STRIP_S.has(token) || token.endsWith("sis")) return token;
+	return pluralize.singular(token);
 }
 const SEPARATOR_RE = /[-_/.@#:+]+/g;
 const WHITESPACE_RE = /\s+/g;
+const DIACRITICS_RE = /\p{Diacritic}/gu;
+const NORMALIZER_VERSION = 2;
+function foldUnicode(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) {
-	return query.toLowerCase().replace(SEPARATOR_RE, " ").replace(WHITESPACE_RE, " ").trim().split(" ").filter(Boolean).map((token) => SYNONYMS[token] ?? token).filter(Boolean).map(depluralize).sort().join(" ");
+	const cleaned = foldUnicode(query).toLowerCase().replace(SEPARATOR_RE, " ").replace(WHITESPACE_RE, " ").trim().split(" ").filter(Boolean);
+	const mapped = cleaned.map((token) => SYNONYMS[token] ?? token).filter(Boolean);
+	const tokens = (mapped.length > 0 ? mapped : cleaned).map(depluralize);
+	return (isOrderSensitive(tokens) ? tokens : tokens.sort()).join(" ");
 }
 const dataDetailAnalyzer = defineAnalyzer$1({
 	id: "data-detail",
@@ -7108,4 +7292,4 @@ function createInMemoryQuerySource(options) {
 	};
 }
 const SQL_ANALYZERS = ALL_ANALYZERS.flatMap((d) => d.sql ? [d.sql] : []);
-export { AnalyzerCapabilityError, DEFAULT_PRIORITY_SOURCES, ENGINE_QUERY_CAPABILITIES, IN_MEMORY_DEFAULT_CAPABILITIES, REPORTS, ROW_ANALYZERS, SQL_ANALYZERS, analysisErrorToException, analysisErrors, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzePageConcentration, analyzeSeasonality, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, diffSitemapHealth, dryRunReport, formatAnalysisError, formatReport, isAnalysisError, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, runReportResult, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };
+export { AnalyzerCapabilityError, DEFAULT_PRIORITY_SOURCES, ENGINE_QUERY_CAPABILITIES, INTENT_CLASSIFIER_VERSION, IN_MEMORY_DEFAULT_CAPABILITIES, NORMALIZER_VERSION, REPORTS, ROW_ANALYZERS, SEARCH_INTENT_CODE, SQL_ANALYZERS, analysisErrorToException, analysisErrors, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzePageConcentration, analyzeSeasonality, classifyQueryIntent, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, decodeIntent, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, diffSitemapHealth, dryRunReport, encodeIntent, formatAnalysisError, formatReport, isAnalysisError, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, runReportResult, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/analysis",
   "type": "module",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "GSC analyzers — striking-distance, opportunity, movers, decay, brand, clustering, concentration, seasonality. Pure row-based + DuckDB-native.",
   "author": {
     "name": "Harlan Wilton",
@@ -75,9 +75,10 @@
   },
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
-    "@gscdump/engine": "0.30.0",
-    "@gscdump/engine-gsc-api": "0.30.0",
-    "gscdump": "0.30.0"
+    "pluralize": "^8.0.0",
+    "@gscdump/engine-gsc-api": "0.31.0",
+    "@gscdump/engine": "0.31.0",
+    "gscdump": "0.31.0"
   },
   "devDependencies": {
     "vitest": "^4.1.9"