@gscdump/analysis 1.0.2 → 1.0.4

package/dist/errors.d.mts

@@ -1,52 +1,2 @@
-type AnalysisErrorKind = 'missing-report-param' | 'missing-comparison-window' | 'missing-brand-terms' | 'unknown-report' | 'unknown-analyzer' | 'required-step-failed';
-type AnalysisError = {
-  kind: 'missing-report-param';
-  report: string;
-  param: string;
-  message: string;
-} | {
-  kind: 'missing-comparison-window';
-  report: string;
-  message: string;
-} | {
-  kind: 'missing-brand-terms';
-  message: string;
-} | {
-  kind: 'unknown-report';
-  report: string;
-  available: readonly string[];
-  message: string;
-} | {
-  kind: 'unknown-analyzer';
-  analyzer: string;
-  message: string;
-} | {
-  kind: 'required-step-failed';
-  report: string;
-  stepKey: string;
-  stepError: string;
-  message: string;
-  cause?: unknown;
-};
-declare const analysisErrors: {
-  readonly missingReportParam: (report: string, param: string, message: string) => AnalysisError;
-  readonly missingComparisonWindow: (report: string, message: string) => AnalysisError;
-  readonly missingBrandTerms: () => AnalysisError;
-  readonly unknownReport: (report: string, available: readonly string[]) => AnalysisError;
-  readonly unknownAnalyzer: (analyzer: string) => AnalysisError;
-  readonly requiredStepFailed: (report: string, stepKey: string, stepError: string, cause?: unknown) => AnalysisError;
-};
-declare function isAnalysisError(value: unknown): value is AnalysisError;
-/** The human-readable rendering of an `AnalysisError`, for logs and string sinks. */
-declare function formatAnalysisError(error: AnalysisError): string;
-/**
- * Re-raises an `AnalysisError` value as a generic `Error`, stashing the union
- * under `.analysisError` for stack-walking and preserving the original `cause`
- * (so a `required-step-failed` keeps the underlying thrown value reachable).
- * Used by the throwing wrappers over the `Result`-returning cores. The thrown
- * `.message` is kept verbatim from the union, so existing message-regex
- * assertions (`/--target/`, `/comparison window/`, `/required step "k"/`)
- * continue to match.
- */
-declare function analysisErrorToException(error: AnalysisError): Error;
+import { AnalysisError, AnalysisErrorKind, analysisErrorToException, analysisErrors, formatAnalysisError, isAnalysisError } from "./_chunks/errors.mjs";
 export { AnalysisError, AnalysisErrorKind, analysisErrorToException, analysisErrors, formatAnalysisError, isAnalysisError };

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-import { Analyzer, Analyzer as Analyzer$1, AnalyzerCapabilityError, AnalyzerRegistry, AnalyzerRegistry as AnalyzerRegistry$1, AnalyzerRegistryInit, AnalyzerVariants, DefineAnalyzerOptions, DefinedAnalyzer, Plan, ReduceContext, ReduceCtx, Reducer, RequiredCapability, RowQueriesPlan, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource } from "@gscdump/engine/analyzer";
+import { ROW_ANALYZERS, SQL_ANALYZERS, defaultAnalyzerRegistry } from "./_chunks/default-registry.mjs";
+import { AnalysisError, AnalysisErrorKind, analysisErrorToException, analysisErrors, formatAnalysisError, isAnalysisError } from "./_chunks/errors.mjs";
+import { DryRunReportResult, FormatReportOptions, REPORTS, RunReportOptions, defaultReportRegistry, dryRunReport, formatReport, runReport, runReportResult } from "./_chunks/index.mjs";
+import { CompositeSourceOptions, IN_MEMORY_DEFAULT_CAPABILITIES, InMemoryQuerySourceOptions, createCompositeSource, createInMemoryQuerySource } from "./_chunks/index2.mjs";
+import { Analyzer, AnalyzerCapabilityError, AnalyzerRegistry, AnalyzerRegistry as AnalyzerRegistry$1, AnalyzerRegistryInit, AnalyzerVariants, DefineAnalyzerOptions, DefinedAnalyzer, Plan, ReduceContext, ReduceCtx, Reducer, RequiredCapability, RowQueriesPlan, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource } from "@gscdump/engine/analyzer";
 import { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, padTimeseries, periodOf, resolveWindow } from "@gscdump/engine/period";
 import { AnalysisParams, AnalysisParams as AnalysisParams$1, AnalysisResult, AnalysisResult as AnalysisResult$1, AnalysisTool, num } from "@gscdump/engine/analysis-types";
-import { Result } from "gscdump/result";
-import { BuilderState } from "gscdump/query";
-import { AnalysisQuerySource, AnalysisQuerySource as AnalysisQuerySource$1, AnalysisSourceKind, AttachedTableRunner, AttachedTableRunner as AnalyzerRunner, AttachedTableSourceOptions, AttachedTableSourceOptions as BrowserAnalyzeOptions, ENGINE_QUERY_CAPABILITIES, EngineQuerySourceOptions, ExecuteSqlOptions, FileSet, QueryRow, QueryRow as QueryRow$1, SourceCapabilities, createEngineQuerySource, queryRows, runAnalyzerWithEngine } from "@gscdump/engine/source";
-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";
+import { AnalysisQuerySource, AnalysisSourceKind, AttachedTableRunner, AttachedTableRunner as AnalyzerRunner, AttachedTableSourceOptions, AttachedTableSourceOptions as BrowserAnalyzeOptions, ENGINE_QUERY_CAPABILITIES, EngineQuerySourceOptions, ExecuteSqlOptions, FileSet, QueryRow, SourceCapabilities, createEngineQuerySource, queryRows, runAnalyzerWithEngine } from "@gscdump/engine/source";
+import { DefineReportOptions, DefinedReport, ReportAction, ReportContext, ReportFinding, ReportPlanStep, ReportResult, ReportSection } from "@gscdump/engine/report";
 type ActionSource = 'cannibalization' | 'striking-distance' | 'ctr-anomaly' | 'change-point' | 'opportunity';
 type Effort = 'low' | 'medium' | 'high';
 interface PriorityAction {
@@ -38,7 +39,6 @@ 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 const ROW_ANALYZERS: readonly Analyzer$1[];
 /**
  * Domain row shapes + analysis utilities. Analyzer-call contracts
  * (`AnalysisParams`, `AnalysisResult`, `AnalysisTool`, `num`) live in
@@ -428,64 +428,6 @@ interface ZeroClickOptions {
 /** Pure zero-click detector shared by hosted and package analyzer callers. */
 declare function analyzeZeroClick(rows: QueryPageRow[], options?: ZeroClickOptions): ZeroClickResult[];
 declare function analyzeInBrowser(runner: AttachedTableRunner, opts: AttachedTableSourceOptions, params: AnalysisParams$1, registry: AnalyzerRegistry$1): Promise<AnalysisResult$1>;
-/**
- * Default analyzer registry built from every in-tree analyzer. Convenience
- * for callers who don't care about bundle size; edge / browser consumers
- * should compose their own narrower registry via `createAnalyzerRegistry`
- * with the flat `ROW_ANALYZERS` / `SQL_ANALYZERS` arrays.
- */
-declare const defaultAnalyzerRegistry: import("@gscdump/engine/analyzer").AnalyzerRegistry;
-type AnalysisErrorKind = 'missing-report-param' | 'missing-comparison-window' | 'missing-brand-terms' | 'unknown-report' | 'unknown-analyzer' | 'required-step-failed';
-type AnalysisError = {
-  kind: 'missing-report-param';
-  report: string;
-  param: string;
-  message: string;
-} | {
-  kind: 'missing-comparison-window';
-  report: string;
-  message: string;
-} | {
-  kind: 'missing-brand-terms';
-  message: string;
-} | {
-  kind: 'unknown-report';
-  report: string;
-  available: readonly string[];
-  message: string;
-} | {
-  kind: 'unknown-analyzer';
-  analyzer: string;
-  message: string;
-} | {
-  kind: 'required-step-failed';
-  report: string;
-  stepKey: string;
-  stepError: string;
-  message: string;
-  cause?: unknown;
-};
-declare const analysisErrors: {
-  readonly missingReportParam: (report: string, param: string, message: string) => AnalysisError;
-  readonly missingComparisonWindow: (report: string, message: string) => AnalysisError;
-  readonly missingBrandTerms: () => AnalysisError;
-  readonly unknownReport: (report: string, available: readonly string[]) => AnalysisError;
-  readonly unknownAnalyzer: (analyzer: string) => AnalysisError;
-  readonly requiredStepFailed: (report: string, stepKey: string, stepError: string, cause?: unknown) => AnalysisError;
-};
-declare function isAnalysisError(value: unknown): value is AnalysisError;
-/** The human-readable rendering of an `AnalysisError`, for logs and string sinks. */
-declare function formatAnalysisError(error: AnalysisError): string;
-/**
- * Re-raises an `AnalysisError` value as a generic `Error`, stashing the union
- * under `.analysisError` for stack-walking and preserving the original `cause`
- * (so a `required-step-failed` keeps the underlying thrown value reachable).
- * Used by the throwing wrappers over the `Result`-returning cores. The thrown
- * `.message` is kept verbatim from the union, so existing message-regex
- * assertions (`/--target/`, `/comparison window/`, `/required step "k"/`)
- * continue to match.
- */
-declare function analysisErrorToException(error: AnalysisError): Error;
 declare const INTENT_CLASSIFIER_VERSION = 1;
 type SearchIntent = 'transactional' | 'commercial' | 'informational' | 'unknown';
 interface IntentClassification {
@@ -519,61 +461,6 @@ declare const NORMALIZER_VERSION = 2;
  * 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: import("@gscdump/engine/report").ReportRegistry;
-interface RunReportOptions<P extends ReportParams = ReportParams> {
-  source: AnalysisQuerySource$1;
-  analyzers: AnalyzerRegistry$1;
-  ctx: ReportContext$1<P>;
-}
-/**
- * `Result`-returning core for {@link runReport}. Models the one
- * caller-actionable failure of a structurally-valid report run: a required
- * step's analyzer threw (`required-step-failed`, with the underlying error as
- * `cause`). Hosts can map that to a 4xx/partial response instead of catching an
- * untyped `Error`.
- *
- * 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).
- *
- * The report's own `plan()` param-validation throws (`--target` etc.) are
- * defects from this core's perspective and still propagate; those are modelled
- * at the report-definition boundary, not here.
- */
-declare function runReportResult<P extends ReportParams = ReportParams>(report: DefinedReport$1<P>, opts: RunReportOptions<P>): Promise<Result<ReportResult$1, AnalysisError>>;
-/**
- * Throwing wrapper over {@link runReportResult}, preserving the historical
- * call-site ergonomics (a required-step failure rejects). The thrown message is
- * kept verbatim (`runReport(id): required step "k" failed: ...`) so existing
- * assertions hold; the typed `AnalysisError` is reachable via `.analysisError`
- * and the original failure via `.cause`.
- */
-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>;
 interface SitemapHealthRow {
   path: string;
   errors: number;
@@ -607,38 +494,4 @@ interface SitemapHealthDiff {
   totals: SitemapHealthTotals;
 }
 declare function diffSitemapHealth(prev: readonly SitemapHealthRow[], curr: readonly SitemapHealthInput[]): SitemapHealthDiff;
-interface SyncedRange {
-  oldestDateSynced: string | null;
-  newestDateSynced: string | null;
-  /**
-   * Optional sorted list of `[start, end]` daily-key spans (`YYYY-MM-DD`,
-   * both inclusive) that the engine actually has partitions for. When set,
-   * `shouldRouteToLive` returns true for any requested range that overlaps
-   * a day NOT inside one of these spans — even when the request sits inside
-   * `oldestDateSynced..newestDateSynced`. Lets the composite catch *internal*
-   * manifest gaps (e.g. a missing monthly tier) that the outer envelope
-   * doesn't reveal. Spans must be sorted by `start` and non-overlapping.
-   */
-  coveredSpans?: ReadonlyArray<{
-    start: string;
-    end: string;
-  }>;
-}
-interface CompositeSourceOptions {
-  engine: AnalysisQuerySource$1;
-  live: AnalysisQuerySource$1;
-  site: SyncedRange;
-}
-declare function createCompositeSource(opts: CompositeSourceOptions): AnalysisQuerySource$1;
-/**
- * Permissive defaults: in-memory sources are usually test doubles, so they
- * advertise every capability unless the test explicitly narrows them.
- */
-declare const IN_MEMORY_DEFAULT_CAPABILITIES: PlannerCapabilities;
-interface InMemoryQuerySourceOptions {
-  queryRows: (state: BuilderState) => Promise<QueryRow$1[]> | QueryRow$1[];
-  capabilities?: PlannerCapabilities;
-}
-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 BrandSegmentationRow, 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 OpportunityFactors, type OpportunityOptions, type OpportunityResult, type OpportunitySortMetric, type OpportunityWeights, 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 StrikingDistanceOptions, type StrikingDistanceResult, type TypedRowQuery, type WindowPreset, type ZeroClickOptions, type ZeroClickResult, analysisErrorToException, analysisErrors, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, classifyQueryIntent, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, diffSitemapHealth, dryRunReport, encodeIntent, formatAnalysisError, formatReport, isAnalysisError, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryRows, resolveWindow, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, runReportResult, scorePriorityActions };