@gscdump/analysis 0.8.2 → 0.9.1

package/README.md

@@ -49,14 +49,24 @@ const movers = analyzeMovers(currentRows, previousRows)
 const decay = analyzeDecay(currentRows, previousRows)
 ```
 
-Meta-analysis helpers are available too:
+Meta-analyses live in the report layer. Run a composed, ranked priority list via `runReport`:
 
 ```ts
-import { analyzeActionPriority } from '@gscdump/analysis'
-
-const prioritized = await analyzeActionPriority({
-  analyze: params => runner.analyze(params),
+import {
+  defaultAnalyzerRegistry,
+  defaultReportRegistry,
+  runReport,
+} from '@gscdump/analysis'
+import { resolveWindow } from '@gscdump/engine/period'
+
+const report = defaultReportRegistry.getReport('priority')!
+const window = resolveWindow({ preset: 'last-28d', comparison: 'prev-period' })
+const result = await runReport(report, {
+  source,
+  analyzers: defaultAnalyzerRegistry,
+  ctx: { site: siteUrl, window, params: {}, registryVersion: defaultReportRegistry.version },
 })
+// result.sections[0].findings — ranked priority actions, page+query keyed.
 ```
 
 Source adapters compose a GSC client + analyzer in one call:

package/dist/analyzer/index.mjs

@@ -2754,8 +2754,7 @@ const keywordBreadthAnalyzer = defineAnalyzer({
       FROM per_page
     )
     SELECT
-      (SELECT to_json(list({ 'bucket': bucket, 'pageCount': pageCount, 'sortKey': sort_key })
-        ORDER BY sort_key ASC) FROM bucketed) AS distribution_json,
+      (SELECT to_json(list({ 'bucket': bucket, 'pageCount': pageCount, 'sortKey': sort_key })) FROM bucketed) AS distribution_json,
       (SELECT to_json(list({ 'url': url, 'keywordCount': keywordCount, 'clicks': clicks, 'impressions': impressions })) FROM fragile) AS fragile_json,
       (SELECT to_json(list({ 'url': url, 'keywordCount': keywordCount, 'clicks': clicks, 'impressions': impressions })) FROM authority) AS authority_json,
       (SELECT to_json({

package/dist/default-registry.mjs

@@ -3570,8 +3570,7 @@ const keywordBreadthAnalyzer = defineAnalyzer({
       FROM per_page
     )
     SELECT
-      (SELECT to_json(list({ 'bucket': bucket, 'pageCount': pageCount, 'sortKey': sort_key })
-        ORDER BY sort_key ASC) FROM bucketed) AS distribution_json,
+      (SELECT to_json(list({ 'bucket': bucket, 'pageCount': pageCount, 'sortKey': sort_key })) FROM bucketed) AS distribution_json,
       (SELECT to_json(list({ 'url': url, 'keywordCount': keywordCount, 'clicks': clicks, 'impressions': impressions })) FROM fragile) AS fragile_json,
       (SELECT to_json(list({ 'url': url, 'keywordCount': keywordCount, 'clicks': clicks, 'impressions': impressions })) FROM authority) AS authority_json,
       (SELECT to_json({

package/dist/index.d.mts

@@ -1,10 +1,12 @@
+import { AnalysisParams, AnalysisParams as AnalysisParams$1, AnalysisResult, AnalysisResult as AnalysisResult$1, AnalysisTool, num } from "@gscdump/engine/analysis-types";
 import * as _$_gscdump_engine_analyzer0 from "@gscdump/engine/analyzer";
 import { Analyzer, Analyzer as Analyzer$1, AnalyzerCapabilityError, AnalyzerRegistry, AnalyzerRegistry as AnalyzerRegistry$1, AnalyzerRegistryInit, AnalyzerVariants, Capability, DefineAnalyzerOptions, DefinedAnalyzer, Plan, ReduceContext, ReduceCtx, Reducer, RowQueriesPlan, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource } from "@gscdump/engine/analyzer";
-import { AnalysisParams, AnalysisParams as AnalysisParams$1, AnalysisResult, AnalysisResult as AnalysisResult$1, AnalysisTool, num } from "@gscdump/engine/analysis-types";
 import { AnalysisPeriod, AnalysisPeriod as AnalysisPeriod$1, ComparisonMode, ComparisonPeriod, ComparisonPeriod as ComparisonPeriod$1, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod } from "@gscdump/engine/period";
 import { BuilderState } from "gscdump/query";
 import { AttachedTableRunner, AttachedTableRunner as AnalyzerRunner, AttachedTableSourceOptions, AttachedTableSourceOptions as BrowserAnalyzeOptions, ENGINE_QUERY_CAPABILITIES, EngineQuerySourceOptions, TypedQuery, createEngineQuerySource, queryComparisonRows, queryRows, rewriteForTableSource, runAnalyzerWithEngine, typedQuery } from "@gscdump/engine/source";
 import { AnalysisQuerySource, AnalysisQuerySource as AnalysisQuerySource$1, ExecuteSqlOptions, FileSet, QueryRow, QueryRow as QueryRow$1, RowQuerySource, RowQuerySource as RowQuerySource$1, SourceCapabilities, SqlQuerySource, SqlQuerySource as SqlQuerySource$1, isSqlQuerySource } from "@gscdump/engine/resolver";
+import * as _$_gscdump_engine_report0 from "@gscdump/engine/report";
+import { DefineReportOptions, DefinedReport, DefinedReport as DefinedReport$1, ReportAction, ReportContext, ReportContext as ReportContext$1, ReportFinding, ReportParams, ReportPlanStep, ReportResult, ReportResult as ReportResult$1, ReportSection } from "@gscdump/engine/report";
 import { PlannerCapabilities } from "gscdump/query/plan";
 type ActionSource = 'cannibalization' | 'striking-distance' | 'ctr-anomaly' | 'change-point' | 'opportunity';
 type Effort = 'low' | 'medium' | 'high';
@@ -34,29 +36,10 @@ interface ActionPriorityResult {
   totalSignals: number;
   sources: ActionPrioritySourceState[];
 }
-interface ActionPriorityRunOptions {
-  sources?: ActionSource[];
-  limit?: number;
-  continueOnError?: boolean;
-  paramsBySource?: Partial<Record<ActionSource, Omit<AnalysisParams$1, 'type'>>>;
-  onSourceStatus?: (state: ActionPrioritySourceState) => void;
-}
-interface ActionPriorityAnalyzer {
-  analyze: (params: AnalysisParams$1) => Promise<AnalysisResult$1>;
-}
+declare const DEFAULT_PRIORITY_SOURCES: ActionSource[];
 declare function normalizePriorityActions(source: ActionSource, result: AnalysisResult$1): PriorityAction[];
 declare function mergePriorityActions(all: PriorityAction[]): PriorityAction[];
 declare function scorePriorityActions(actions: PriorityAction[]): PriorityAction[];
-declare function analyzeActionPriority(analyzer: ActionPriorityAnalyzer, options?: ActionPriorityRunOptions): Promise<ActionPriorityResult>;
-/**
- * Convenience wrapper: build the analyzer callback from an
- * {@link AnalysisQuerySource} so consumers don't hand-roll the adapter.
- * SQL-only tools (e.g. `cannibalization`, `ctr-anomaly`, `change-point`) will
- * surface as `status: 'error'` on their source state when the source lacks a
- * row-based implementation — `continueOnError` defaults to true, so the
- * overall run still produces whatever the other analyzers found.
- */
-declare function analyzeActionPriorityFromSource(source: AnalysisQuerySource$1, registry: AnalyzerRegistry$1, options?: ActionPriorityRunOptions): Promise<ActionPriorityResult>;
 declare const ROW_ANALYZERS: readonly Analyzer$1[];
 /**
  * Domain row shapes + analysis utilities. Analyzer-call contracts
@@ -379,6 +362,44 @@ declare const defaultAnalyzerRegistry: _$_gscdump_engine_analyzer0.AnalyzerRegis
  * Idempotent: `normalizeQuery(normalizeQuery(q)) === normalizeQuery(q)`.
  */
 declare function normalizeQuery(query: string): string;
+interface FormatReportOptions {
+  /** Cap findings rendered per section. Defaults to all (already bounded by report). */
+  maxFindingsPerSection?: number;
+}
+declare function formatReport(report: ReportResult$1, opts?: FormatReportOptions): string;
+declare const REPORTS: readonly DefinedReport$1<ReportParams>[];
+declare const defaultReportRegistry: _$_gscdump_engine_report0.ReportRegistry;
+interface RunReportOptions<P extends ReportParams = ReportParams> {
+  source: AnalysisQuerySource$1;
+  analyzers: AnalyzerRegistry$1;
+  ctx: ReportContext$1<P>;
+}
+/**
+ * Run a defined report against a source. Steps execute in parallel via
+ * `Promise.all`. The report's `reduce` is invoked with a results bag that
+ * only contains successful steps — sections that depended on a failed step
+ * should set their own `coverage: 'partial'` (the runtime additionally
+ * marks `meta.degraded` when any step errored).
+ */
+declare function runReport<P extends ReportParams = ReportParams>(report: DefinedReport$1<P>, opts: RunReportOptions<P>): Promise<ReportResult$1>;
+interface DryRunReportResult {
+  steps: {
+    key: string;
+    type: string;
+    estRowsScanned?: number;
+  }[];
+  windowResolved: {
+    start: string;
+    end: string;
+    days: number;
+  };
+}
+/**
+ * Plan-only preview. v1 doesn't compute row estimates — analyzer-level
+ * cost models don't exist yet — so `estRowsScanned` is left undefined.
+ * Useful right now only as an "is this report wired up correctly?" check.
+ */
+declare function dryRunReport<P extends ReportParams = ReportParams>(report: DefinedReport$1<P>, ctx: ReportContext$1<P>): Promise<DryRunReportResult>;
 declare function analyzeFromSource(source: AnalysisQuerySource$1, params: AnalysisParams$1, registry: AnalyzerRegistry$1): Promise<AnalysisResult$1>;
 interface CompositeSourceOptions {
   engine: SqlQuerySource$1;
@@ -458,4 +479,4 @@ declare function analyzeSeasonalityFromSource(source: AnalysisQuerySource$1, per
 declare function analyzeDecayFromSource(source: AnalysisQuerySource$1, periods: ComparisonPeriod$1, options?: DecayOptions): Promise<DecayResult[]>;
 declare function analyzeMoversFromSource(source: AnalysisQuerySource$1, periods: ComparisonPeriod$1, options?: MoversOptions): Promise<MoversResult>;
 declare const SQL_ANALYZERS: readonly Analyzer$1[];
-export { type ActionPriorityAnalyzer, type ActionPriorityResult, type ActionPriorityRunOptions, type ActionPrioritySourceState, type ActionPrioritySourceStatus, type ActionSource, type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, 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 Capability, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type ComparisonQueryResult, type CompositeSourceOptions, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefinedAnalyzer, ENGINE_QUERY_CAPABILITIES, type Effort, type EngineQuerySourceOptions, type ExecuteSqlOptions, type FileSet, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type KeywordCluster, type KeywordRow, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, type OpportunityResult, type PadTimeseriesOptions, type PageRow, type Plan, type PriorityAction, type QueryDimension, type QueryOptions, type QueryPageRow, type QueryResult, type QueryRow, ROW_ANALYZERS, type ReduceContext, type ReduceCtx, type Reducer, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, type RowQuerySource, SQL_ANALYZERS, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type SqlQuerySource, type StrikingDistanceOptions, type StrikingDistanceResult, type StrikingDistanceSortMetric, type TypedQuery, type TypedRowQuery, type WindowPreset, type ZeroClickResult, analyzeActionPriority, analyzeActionPriorityFromSource, analyzeBrandSegmentation, analyzeBrandSegmentationFromSource, analyzeCannibalization, analyzeClustering, analyzeClusteringFromSource, analyzeConcentration, analyzeDecay, analyzeDecayFromSource, analyzeFromSource, analyzeInBrowser, analyzeKeywordConcentration, analyzeKeywordConcentrationFromSource, analyzeMovers, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentration, analyzePageConcentrationFromSource, analyzeSeasonality, analyzeSeasonalityFromSource, analyzeStrikingDistance, analyzeStrikingDistanceFromSource, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defineAnalyzer, isSqlQuerySource, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };
+export { type ActionPriorityResult, type ActionPrioritySourceState, type ActionPrioritySourceStatus, type ActionSource, type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, 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 Capability, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type ComparisonQueryResult, 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 KeywordRow, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, type OpportunityResult, type PadTimeseriesOptions, type PageRow, type Plan, type PriorityAction, type QueryDimension, type QueryOptions, type QueryPageRow, type QueryResult, type QueryRow, REPORTS, ROW_ANALYZERS, type ReduceContext, type ReduceCtx, type Reducer, type ReportAction, type ReportContext, type ReportFinding, type ReportPlanStep, type ReportResult, type ReportSection, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, type RowQuerySource, type RunReportOptions, SQL_ANALYZERS, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type SqlQuerySource, type StrikingDistanceOptions, type StrikingDistanceResult, type StrikingDistanceSortMetric, type TypedQuery, type TypedRowQuery, type WindowPreset, type ZeroClickResult, analyzeBrandSegmentation, analyzeBrandSegmentationFromSource, analyzeCannibalization, analyzeClustering, analyzeClusteringFromSource, analyzeConcentration, analyzeDecay, analyzeDecayFromSource, analyzeFromSource, analyzeInBrowser, analyzeKeywordConcentration, analyzeKeywordConcentrationFromSource, analyzeMovers, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentration, analyzePageConcentrationFromSource, analyzeSeasonality, analyzeSeasonalityFromSource, analyzeStrikingDistance, analyzeStrikingDistanceFromSource, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, dryRunReport, formatReport, isSqlQuerySource, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };