@gscdump/analysis 0.25.13 → 0.26.0

package/dist/analyzer/index.mjs

@@ -3,6 +3,7 @@ import { comparisonOf, defaultEndDate, padTimeseries, periodOf } from "@gscdump/
 import { enumeratePartitions } from "@gscdump/engine/planner";
 import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
 import { num } from "@gscdump/engine/analysis-types";
+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, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
@@ -445,12 +446,72 @@ function pagesQueryState(period, limit = DEFAULT_LIMIT$1) {
 function datesQueryState(period, limit = DEFAULT_LIMIT$1) {
 	return gsc.select(date).where(between(date, period.startDate, period.endDate)).limit(limit).getState();
 }
+const analysisErrors = {
+	missingReportParam(report, param, message) {
+		return {
+			kind: "missing-report-param",
+			report,
+			param,
+			message
+		};
+	},
+	missingComparisonWindow(report, message) {
+		return {
+			kind: "missing-comparison-window",
+			report,
+			message
+		};
+	},
+	missingBrandTerms() {
+		return {
+			kind: "missing-brand-terms",
+			message: "Brand analysis requires brandTerms"
+		};
+	},
+	unknownReport(report, available) {
+		return {
+			kind: "unknown-report",
+			report,
+			available,
+			message: `unknown report "${report}"; available: ${available.join(", ")}`
+		};
+	},
+	unknownAnalyzer(analyzer) {
+		return {
+			kind: "unknown-analyzer",
+			analyzer,
+			message: `unknown analyzer "${analyzer}"`
+		};
+	},
+	requiredStepFailed(report, stepKey, stepError, cause) {
+		return {
+			kind: "required-step-failed",
+			report,
+			stepKey,
+			stepError,
+			cause,
+			message: `runReport(${report}): required step "${stepKey}" failed: ${stepError}`
+		};
+	}
+};
+function analysisErrorToException(error) {
+	const exception = new Error(error.message);
+	if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+	exception.analysisError = error;
+	return exception;
+}
 function escapeRegexAlt(s) {
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function str$21(v) {
 	return v == null ? "" : String(v);
 }
+function requireBrandTermsResult(brandTerms) {
+	return brandTerms?.length ? ok(brandTerms) : err(analysisErrors.missingBrandTerms());
+}
+function requireBrandTerms(brandTerms) {
+	return unwrapResult(requireBrandTermsResult(brandTerms), analysisErrorToException);
+}
 function analyzeBrandSegmentation(keywords, options) {
 	const { brandTerms, minImpressions = 10 } = options;
 	const lowerBrandTerms = brandTerms.map((t) => t.toLowerCase());
@@ -479,11 +540,11 @@ function analyzeBrandSegmentation(keywords, options) {
 const brandAnalyzer = defineAnalyzer({
 	id: "brand",
 	buildSql(params) {
-		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const brandTerms = requireBrandTerms(params.brandTerms);
 		const { startDate, endDate } = periodOf(params);
 		const minImpressions = params.minImpressions ?? 10;
 		const limit = params.limit ?? 1e4;
-		const regex = `(${params.brandTerms.map((t) => escapeRegexAlt(t.toLowerCase())).join("|")})`;
+		const regex = `(${brandTerms.map((t) => escapeRegexAlt(t.toLowerCase())).join("|")})`;
 		return {
 			sql: `
     WITH agg AS (
@@ -558,9 +619,9 @@ const brandAnalyzer = defineAnalyzer({
 		return { queries: queriesQueryState(periodOf(params), params.limit) };
 	},
 	reduceRows(rows, params) {
-		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const brandTerms = requireBrandTerms(params.brandTerms);
 		const result = analyzeBrandSegmentation(Array.isArray(rows) ? rows : [], {
-			brandTerms: params.brandTerms,
+			brandTerms,
 			minImpressions: params.minImpressions
 		});
 		return {

package/dist/default-registry.mjs

@@ -3,6 +3,7 @@ import { comparisonOf, defaultEndDate, padTimeseries, periodOf } from "@gscdump/
 import { enumeratePartitions } from "@gscdump/engine/planner";
 import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
 import { num } from "@gscdump/engine/analysis-types";
+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, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "@gscdump/engine/resolver";
@@ -445,12 +446,72 @@ function pagesQueryState(period, limit = DEFAULT_LIMIT$1) {
 function datesQueryState(period, limit = DEFAULT_LIMIT$1) {
 	return gsc.select(date).where(between(date, period.startDate, period.endDate)).limit(limit).getState();
 }
+const analysisErrors = {
+	missingReportParam(report, param, message) {
+		return {
+			kind: "missing-report-param",
+			report,
+			param,
+			message
+		};
+	},
+	missingComparisonWindow(report, message) {
+		return {
+			kind: "missing-comparison-window",
+			report,
+			message
+		};
+	},
+	missingBrandTerms() {
+		return {
+			kind: "missing-brand-terms",
+			message: "Brand analysis requires brandTerms"
+		};
+	},
+	unknownReport(report, available) {
+		return {
+			kind: "unknown-report",
+			report,
+			available,
+			message: `unknown report "${report}"; available: ${available.join(", ")}`
+		};
+	},
+	unknownAnalyzer(analyzer) {
+		return {
+			kind: "unknown-analyzer",
+			analyzer,
+			message: `unknown analyzer "${analyzer}"`
+		};
+	},
+	requiredStepFailed(report, stepKey, stepError, cause) {
+		return {
+			kind: "required-step-failed",
+			report,
+			stepKey,
+			stepError,
+			cause,
+			message: `runReport(${report}): required step "${stepKey}" failed: ${stepError}`
+		};
+	}
+};
+function analysisErrorToException(error) {
+	const exception = new Error(error.message);
+	if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+	exception.analysisError = error;
+	return exception;
+}
 function escapeRegexAlt(s) {
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function str$21(v) {
 	return v == null ? "" : String(v);
 }
+function requireBrandTermsResult(brandTerms) {
+	return brandTerms?.length ? ok(brandTerms) : err(analysisErrors.missingBrandTerms());
+}
+function requireBrandTerms(brandTerms) {
+	return unwrapResult(requireBrandTermsResult(brandTerms), analysisErrorToException);
+}
 function analyzeBrandSegmentation(keywords, options) {
 	const { brandTerms, minImpressions = 10 } = options;
 	const lowerBrandTerms = brandTerms.map((t) => t.toLowerCase());
@@ -479,11 +540,11 @@ function analyzeBrandSegmentation(keywords, options) {
 const brandAnalyzer = defineAnalyzer({
 	id: "brand",
 	buildSql(params) {
-		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const brandTerms = requireBrandTerms(params.brandTerms);
 		const { startDate, endDate } = periodOf(params);
 		const minImpressions = params.minImpressions ?? 10;
 		const limit = params.limit ?? 1e4;
-		const regex = `(${params.brandTerms.map((t) => escapeRegexAlt(t.toLowerCase())).join("|")})`;
+		const regex = `(${brandTerms.map((t) => escapeRegexAlt(t.toLowerCase())).join("|")})`;
 		return {
 			sql: `
     WITH agg AS (
@@ -558,9 +619,9 @@ const brandAnalyzer = defineAnalyzer({
 		return { queries: queriesQueryState(periodOf(params), params.limit) };
 	},
 	reduceRows(rows, params) {
-		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const brandTerms = requireBrandTerms(params.brandTerms);
 		const result = analyzeBrandSegmentation(Array.isArray(rows) ? rows : [], {
-			brandTerms: params.brandTerms,
+			brandTerms,
 			minImpressions: params.minImpressions
 		});
 		return {

package/dist/errors.d.mts

@@ -0,0 +1,52 @@
+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;
+export { AnalysisError, AnalysisErrorKind, analysisErrorToException, analysisErrors, formatAnalysisError, isAnalysisError };

package/dist/errors.mjs

@@ -0,0 +1,69 @@
+const analysisErrors = {
+	missingReportParam(report, param, message) {
+		return {
+			kind: "missing-report-param",
+			report,
+			param,
+			message
+		};
+	},
+	missingComparisonWindow(report, message) {
+		return {
+			kind: "missing-comparison-window",
+			report,
+			message
+		};
+	},
+	missingBrandTerms() {
+		return {
+			kind: "missing-brand-terms",
+			message: "Brand analysis requires brandTerms"
+		};
+	},
+	unknownReport(report, available) {
+		return {
+			kind: "unknown-report",
+			report,
+			available,
+			message: `unknown report "${report}"; available: ${available.join(", ")}`
+		};
+	},
+	unknownAnalyzer(analyzer) {
+		return {
+			kind: "unknown-analyzer",
+			analyzer,
+			message: `unknown analyzer "${analyzer}"`
+		};
+	},
+	requiredStepFailed(report, stepKey, stepError, cause) {
+		return {
+			kind: "required-step-failed",
+			report,
+			stepKey,
+			stepError,
+			cause,
+			message: `runReport(${report}): required step "${stepKey}" failed: ${stepError}`
+		};
+	}
+};
+const ANALYSIS_ERROR_KINDS = new Set([
+	"missing-report-param",
+	"missing-comparison-window",
+	"missing-brand-terms",
+	"unknown-report",
+	"unknown-analyzer",
+	"required-step-failed"
+]);
+function isAnalysisError(value) {
+	return typeof value === "object" && value !== null && ANALYSIS_ERROR_KINDS.has(value.kind) && typeof value.message === "string";
+}
+function formatAnalysisError(error) {
+	return error.message;
+}
+function analysisErrorToException(error) {
+	const exception = new Error(error.message);
+	if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+	exception.analysisError = error;
+	return exception;
+}
+export { analysisErrorToException, analysisErrors, formatAnalysisError, isAnalysisError };

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 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 { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod } 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, TypedQuery, createEngineQuerySource, queryComparisonRows, queryRows, rewriteForTableSource, runAnalyzerWithEngine, typedQuery } 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";
@@ -388,6 +389,57 @@ declare function analyzeInBrowser(runner: AttachedTableRunner, opts: AttachedTab
  * 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;
 /**
  * Produce a canonical form of a search query for grouping near-duplicates.
  * Idempotent: `normalizeQuery(normalizeQuery(q)) === normalizeQuery(q)`.
@@ -406,11 +458,28 @@ interface RunReportOptions<P extends ReportParams = ReportParams> {
   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).
+ * `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 {
@@ -498,4 +567,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 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, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzePageConcentration, analyzeSeasonality, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, diffSitemapHealth, dryRunReport, formatReport, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, 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, 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 };

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { comparisonOf, comparisonOf as comparisonOf$1, defaultEndDate, padTimese
 import { enumeratePartitions } from "@gscdump/engine/planner";
 import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
 import { num, num as num$1 } from "@gscdump/engine/analysis-types";
+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";
@@ -662,12 +663,86 @@ function pagesQueryState(period, limit = DEFAULT_LIMIT$2) {
 function datesQueryState(period, limit = DEFAULT_LIMIT$2) {
 	return gsc.select(date).where(between(date, period.startDate, period.endDate)).limit(limit).getState();
 }
+const analysisErrors = {
+	missingReportParam(report, param, message) {
+		return {
+			kind: "missing-report-param",
+			report,
+			param,
+			message
+		};
+	},
+	missingComparisonWindow(report, message) {
+		return {
+			kind: "missing-comparison-window",
+			report,
+			message
+		};
+	},
+	missingBrandTerms() {
+		return {
+			kind: "missing-brand-terms",
+			message: "Brand analysis requires brandTerms"
+		};
+	},
+	unknownReport(report, available) {
+		return {
+			kind: "unknown-report",
+			report,
+			available,
+			message: `unknown report "${report}"; available: ${available.join(", ")}`
+		};
+	},
+	unknownAnalyzer(analyzer) {
+		return {
+			kind: "unknown-analyzer",
+			analyzer,
+			message: `unknown analyzer "${analyzer}"`
+		};
+	},
+	requiredStepFailed(report, stepKey, stepError, cause) {
+		return {
+			kind: "required-step-failed",
+			report,
+			stepKey,
+			stepError,
+			cause,
+			message: `runReport(${report}): required step "${stepKey}" failed: ${stepError}`
+		};
+	}
+};
+const ANALYSIS_ERROR_KINDS = new Set([
+	"missing-report-param",
+	"missing-comparison-window",
+	"missing-brand-terms",
+	"unknown-report",
+	"unknown-analyzer",
+	"required-step-failed"
+]);
+function isAnalysisError(value) {
+	return typeof value === "object" && value !== null && ANALYSIS_ERROR_KINDS.has(value.kind) && typeof value.message === "string";
+}
+function formatAnalysisError(error) {
+	return error.message;
+}
+function analysisErrorToException(error) {
+	const exception = new Error(error.message);
+	if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+	exception.analysisError = error;
+	return exception;
+}
 function escapeRegexAlt(s) {
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function str$21(v) {
 	return v == null ? "" : String(v);
 }
+function requireBrandTermsResult(brandTerms) {
+	return brandTerms?.length ? ok(brandTerms) : err(analysisErrors.missingBrandTerms());
+}
+function requireBrandTerms(brandTerms) {
+	return unwrapResult(requireBrandTermsResult(brandTerms), analysisErrorToException);
+}
 function analyzeBrandSegmentation(keywords, options) {
 	const { brandTerms, minImpressions = 10 } = options;
 	const lowerBrandTerms = brandTerms.map((t) => t.toLowerCase());
@@ -696,11 +771,11 @@ function analyzeBrandSegmentation(keywords, options) {
 const brandAnalyzer = defineAnalyzer$1({
 	id: "brand",
 	buildSql(params) {
-		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const brandTerms = requireBrandTerms(params.brandTerms);
 		const { startDate, endDate } = periodOf$1(params);
 		const minImpressions = params.minImpressions ?? 10;
 		const limit = params.limit ?? 1e4;
-		const regex = `(${params.brandTerms.map((t) => escapeRegexAlt(t.toLowerCase())).join("|")})`;
+		const regex = `(${brandTerms.map((t) => escapeRegexAlt(t.toLowerCase())).join("|")})`;
 		return {
 			sql: `
     WITH agg AS (
@@ -775,9 +850,9 @@ const brandAnalyzer = defineAnalyzer$1({
 		return { queries: queriesQueryState(periodOf$1(params), params.limit) };
 	},
 	reduceRows(rows, params) {
-		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const brandTerms = requireBrandTerms(params.brandTerms);
 		const result = analyzeBrandSegmentation(Array.isArray(rows) ? rows : [], {
-			brandTerms: params.brandTerms,
+			brandTerms,
 			minImpressions: params.minImpressions
 		});
 		return {
@@ -5347,6 +5422,18 @@ function formatNumber(n) {
 	if (Number.isInteger(n)) return String(n);
 	return n.toFixed(2);
 }
+function requireReportParamResult(report, param, value, message) {
+	return value && value.trim() ? ok(value) : err(analysisErrors.missingReportParam(report, param, message));
+}
+function requireReportParam(report, param, value, message) {
+	return unwrapResult(requireReportParamResult(report, param, value, message), analysisErrorToException);
+}
+function requireComparisonWindowResult(report, window, message) {
+	return window.comparison ? ok(window.comparison) : err(analysisErrors.missingComparisonWindow(report, message));
+}
+function requireComparisonWindow(report, window, message) {
+	return unwrapResult(requireComparisonWindowResult(report, window, message), analysisErrorToException);
+}
 const DEFAULT_MAX$7 = 5;
 const brandReport = defineReport({
 	id: "brand",
@@ -5366,8 +5453,7 @@ const brandReport = defineReport({
 		}
 	},
 	plan: (params, window) => {
-		if (!params.brandTerms || !params.brandTerms.trim()) throw new Error("brand report requires --brand-terms <comma,separated,list>");
-		const brandTerms = params.brandTerms.split(",").map((t) => t.trim()).filter(Boolean);
+		const brandTerms = requireReportParam("brand", "brand-terms", params.brandTerms, "brand report requires --brand-terms <comma,separated,list>").split(",").map((t) => t.trim()).filter(Boolean);
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
@@ -5789,14 +5875,14 @@ const moversReport = defineReport({
 		}
 	},
 	plan: (_params, window) => {
-		if (!window.comparison) throw new Error("movers report requires a comparison window — pass --vs prev-period");
+		const comparison = requireComparisonWindow("movers", window, "movers report requires a comparison window — pass --vs prev-period");
 		const cur = {
 			startDate: window.start,
 			endDate: window.end
 		};
 		const prev = {
-			prevStartDate: window.comparison.start,
-			prevEndDate: window.comparison.end
+			prevStartDate: comparison.start,
+			prevEndDate: comparison.end
 		};
 		return [
 			{
@@ -6204,7 +6290,7 @@ const prePublishReport = defineReport({
 		}
 	},
 	plan: (params, window) => {
-		if (!params.topic) throw new Error("pre-publish report requires --topic <topic-or-url>");
+		requireReportParam("pre-publish", "topic", params.topic, "pre-publish report requires --topic <topic-or-url>");
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
@@ -6410,14 +6496,14 @@ const risksReport = defineReport({
 		default: DEFAULT_MAX$1
 	} },
 	plan: (_params, window) => {
-		if (!window.comparison) throw new Error("risks report requires a comparison window — pass --vs prev-period");
+		const comparison = requireComparisonWindow("risks", window, "risks report requires a comparison window — pass --vs prev-period");
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
 		};
 		const prev = {
-			prevStartDate: window.comparison.start,
-			prevEndDate: window.comparison.end
+			prevStartDate: comparison.start,
+			prevEndDate: comparison.end
 		};
 		return [
 			{
@@ -6674,7 +6760,7 @@ const triageReport = defineReport({
 		}
 	},
 	plan: (params, window) => {
-		if (!params.target) throw new Error("triage report requires --target <page-or-query>");
+		requireReportParam("triage", "target", params.target, "triage report requires --target <page-or-query>");
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
@@ -6844,17 +6930,20 @@ async function executeStep(source, analyzers, step) {
 			status: "done"
 		},
 		result
-	})).catch((err) => {
-		const message = err?.message ?? String(err);
-		return { state: {
-			key: step.key,
-			type: step.type,
-			status: "error",
-			error: message
-		} };
+	})).catch((thrown) => {
+		const message = thrown?.message ?? String(thrown);
+		return {
+			state: {
+				key: step.key,
+				type: step.type,
+				status: "error",
+				error: message
+			},
+			cause: thrown
+		};
 	});
 }
-async function runReport(report, opts) {
+async function runReportResult(report, opts) {
 	const startedAt = Date.now();
 	const generatedAt = new Date(startedAt).toISOString();
 	const inputHash = await computeInputHash({
@@ -6868,13 +6957,13 @@ async function runReport(report, opts) {
 	const outcomes = await Promise.all(steps.map((s) => executeStep(opts.source, opts.analyzers, s)));
 	const required = new Map(steps.filter((s) => s.required).map((s) => [s.key, s]));
 	const errored = outcomes.filter((o) => o.state.status === "error");
-	for (const o of errored) if (required.has(o.state.key)) throw new Error(`runReport(${report.id}): required step "${o.state.key}" failed: ${o.state.error}`);
+	for (const o of errored) if (required.has(o.state.key)) return err(analysisErrors.requiredStepFailed(report.id, o.state.key, o.state.error ?? "unknown error", o.cause));
 	const resultsByKey = {};
 	for (const o of outcomes) if (o.result) resultsByKey[o.state.key] = o.result;
 	const sections = report.reduce(resultsByKey, opts.ctx).sections;
 	const degraded = errored.length > 0;
 	const stepStates = outcomes.map((o) => o.state);
-	return {
+	return ok({
 		id: report.id,
 		site: opts.ctx.site,
 		inputHash,
@@ -6887,7 +6976,10 @@ async function runReport(report, opts) {
 			degraded,
 			steps: stepStates
 		}
-	};
+	});
+}
+async function runReport(report, opts) {
+	return unwrapResult(await runReportResult(report, opts), analysisErrorToException);
 }
 async function dryRunReport(report, ctx) {
 	return {
@@ -6995,4 +7087,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, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzePageConcentration, analyzeSeasonality, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, diffSitemapHealth, dryRunReport, formatReport, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };
+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 };

package/dist/report/index.d.mts

@@ -1,4 +1,5 @@
 import { DefinedReport, ReportContext, ReportParams, ReportResult } from "@gscdump/engine/report";
+import { Result } from "gscdump/result";
 import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
 import { AnalysisQuerySource } from "@gscdump/engine/source";
 interface FormatReportOptions {
@@ -36,17 +37,63 @@ interface ResolveTargetResult {
   unresolved: boolean;
 }
 declare function resolveTarget(opts: ResolveTargetInput): ResolveTargetResult;
+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;
+};
 interface RunReportOptions<P extends ReportParams = ReportParams> {
   source: AnalysisQuerySource;
   analyzers: AnalyzerRegistry;
   ctx: ReportContext<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).
+ * `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<P>, opts: RunReportOptions<P>): Promise<Result<ReportResult, 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<P>, opts: RunReportOptions<P>): Promise<ReportResult>;
 interface DryRunReportResult {
@@ -67,4 +114,4 @@ interface DryRunReportResult {
  * Useful right now only as an "is this report wired up correctly?" check.
  */
 declare function dryRunReport<P extends ReportParams = ReportParams>(report: DefinedReport<P>, ctx: ReportContext<P>): Promise<DryRunReportResult>;
-export { type DryRunReportResult, type FormatReportOptions, REPORTS, type ResolveTargetInput, type ResolveTargetKind, type ResolveTargetResult, type RunReportOptions, defaultReportRegistry, dryRunReport, formatReport, resolveTarget, runReport };
+export { type DryRunReportResult, type FormatReportOptions, REPORTS, type ResolveTargetInput, type ResolveTargetKind, type ResolveTargetResult, type RunReportOptions, defaultReportRegistry, dryRunReport, formatReport, resolveTarget, runReport, runReportResult };

package/dist/report/index.mjs

@@ -1,4 +1,5 @@
 import { computeInputHash, createReportRegistry, defineReport } from "@gscdump/engine/report";
+import { err, ok, unwrapResult } from "gscdump/result";
 import { runAnalyzerFromSource } from "@gscdump/engine/analyzer";
 const SEVERITY_GLYPH = {
 	info: "i",
@@ -44,6 +45,72 @@ function formatNumber(n) {
 	if (Number.isInteger(n)) return String(n);
 	return n.toFixed(2);
 }
+const analysisErrors = {
+	missingReportParam(report, param, message) {
+		return {
+			kind: "missing-report-param",
+			report,
+			param,
+			message
+		};
+	},
+	missingComparisonWindow(report, message) {
+		return {
+			kind: "missing-comparison-window",
+			report,
+			message
+		};
+	},
+	missingBrandTerms() {
+		return {
+			kind: "missing-brand-terms",
+			message: "Brand analysis requires brandTerms"
+		};
+	},
+	unknownReport(report, available) {
+		return {
+			kind: "unknown-report",
+			report,
+			available,
+			message: `unknown report "${report}"; available: ${available.join(", ")}`
+		};
+	},
+	unknownAnalyzer(analyzer) {
+		return {
+			kind: "unknown-analyzer",
+			analyzer,
+			message: `unknown analyzer "${analyzer}"`
+		};
+	},
+	requiredStepFailed(report, stepKey, stepError, cause) {
+		return {
+			kind: "required-step-failed",
+			report,
+			stepKey,
+			stepError,
+			cause,
+			message: `runReport(${report}): required step "${stepKey}" failed: ${stepError}`
+		};
+	}
+};
+function analysisErrorToException(error) {
+	const exception = new Error(error.message);
+	if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+	exception.analysisError = error;
+	return exception;
+}
+function requireReportParamResult(report, param, value, message) {
+	return value && value.trim() ? ok(value) : err(analysisErrors.missingReportParam(report, param, message));
+}
+function requireReportParam(report, param, value, message) {
+	return unwrapResult(requireReportParamResult(report, param, value, message), analysisErrorToException);
+}
+function requireComparisonWindowResult(report, window, message) {
+	return window.comparison ? ok(window.comparison) : err(analysisErrors.missingComparisonWindow(report, message));
+}
+function requireComparisonWindow(report, window, message) {
+	return unwrapResult(requireComparisonWindowResult(report, window, message), analysisErrorToException);
+}
 const DEFAULT_MAX$7 = 5;
 const brandReport = defineReport({
 	id: "brand",
@@ -63,8 +130,7 @@ const brandReport = defineReport({
 		}
 	},
 	plan: (params, window) => {
-		if (!params.brandTerms || !params.brandTerms.trim()) throw new Error("brand report requires --brand-terms <comma,separated,list>");
-		const brandTerms = params.brandTerms.split(",").map((t) => t.trim()).filter(Boolean);
+		const brandTerms = requireReportParam("brand", "brand-terms", params.brandTerms, "brand report requires --brand-terms <comma,separated,list>").split(",").map((t) => t.trim()).filter(Boolean);
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
@@ -486,14 +552,14 @@ const moversReport = defineReport({
 		}
 	},
 	plan: (_params, window) => {
-		if (!window.comparison) throw new Error("movers report requires a comparison window — pass --vs prev-period");
+		const comparison = requireComparisonWindow("movers", window, "movers report requires a comparison window — pass --vs prev-period");
 		const cur = {
 			startDate: window.start,
 			endDate: window.end
 		};
 		const prev = {
-			prevStartDate: window.comparison.start,
-			prevEndDate: window.comparison.end
+			prevStartDate: comparison.start,
+			prevEndDate: comparison.end
 		};
 		return [
 			{
@@ -901,7 +967,7 @@ const prePublishReport = defineReport({
 		}
 	},
 	plan: (params, window) => {
-		if (!params.topic) throw new Error("pre-publish report requires --topic <topic-or-url>");
+		requireReportParam("pre-publish", "topic", params.topic, "pre-publish report requires --topic <topic-or-url>");
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
@@ -1316,14 +1382,14 @@ const risksReport = defineReport({
 		default: DEFAULT_MAX$1
 	} },
 	plan: (_params, window) => {
-		if (!window.comparison) throw new Error("risks report requires a comparison window — pass --vs prev-period");
+		const comparison = requireComparisonWindow("risks", window, "risks report requires a comparison window — pass --vs prev-period");
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
 		};
 		const prev = {
-			prevStartDate: window.comparison.start,
-			prevEndDate: window.comparison.end
+			prevStartDate: comparison.start,
+			prevEndDate: comparison.end
 		};
 		return [
 			{
@@ -1580,7 +1646,7 @@ const triageReport = defineReport({
 		}
 	},
 	plan: (params, window) => {
-		if (!params.target) throw new Error("triage report requires --target <page-or-query>");
+		requireReportParam("triage", "target", params.target, "triage report requires --target <page-or-query>");
 		const dates = {
 			startDate: window.start,
 			endDate: window.end
@@ -1750,17 +1816,20 @@ async function executeStep(source, analyzers, step) {
 			status: "done"
 		},
 		result
-	})).catch((err) => {
-		const message = err?.message ?? String(err);
-		return { state: {
-			key: step.key,
-			type: step.type,
-			status: "error",
-			error: message
-		} };
+	})).catch((thrown) => {
+		const message = thrown?.message ?? String(thrown);
+		return {
+			state: {
+				key: step.key,
+				type: step.type,
+				status: "error",
+				error: message
+			},
+			cause: thrown
+		};
 	});
 }
-async function runReport(report, opts) {
+async function runReportResult(report, opts) {
 	const startedAt = Date.now();
 	const generatedAt = new Date(startedAt).toISOString();
 	const inputHash = await computeInputHash({
@@ -1774,13 +1843,13 @@ async function runReport(report, opts) {
 	const outcomes = await Promise.all(steps.map((s) => executeStep(opts.source, opts.analyzers, s)));
 	const required = new Map(steps.filter((s) => s.required).map((s) => [s.key, s]));
 	const errored = outcomes.filter((o) => o.state.status === "error");
-	for (const o of errored) if (required.has(o.state.key)) throw new Error(`runReport(${report.id}): required step "${o.state.key}" failed: ${o.state.error}`);
+	for (const o of errored) if (required.has(o.state.key)) return err(analysisErrors.requiredStepFailed(report.id, o.state.key, o.state.error ?? "unknown error", o.cause));
 	const resultsByKey = {};
 	for (const o of outcomes) if (o.result) resultsByKey[o.state.key] = o.result;
 	const sections = report.reduce(resultsByKey, opts.ctx).sections;
 	const degraded = errored.length > 0;
 	const stepStates = outcomes.map((o) => o.state);
-	return {
+	return ok({
 		id: report.id,
 		site: opts.ctx.site,
 		inputHash,
@@ -1793,7 +1862,10 @@ async function runReport(report, opts) {
 			degraded,
 			steps: stepStates
 		}
-	};
+	});
+}
+async function runReport(report, opts) {
+	return unwrapResult(await runReportResult(report, opts), analysisErrorToException);
 }
 async function dryRunReport(report, ctx) {
 	return {
@@ -1808,4 +1880,4 @@ async function dryRunReport(report, ctx) {
 		}
 	};
 }
-export { REPORTS, defaultReportRegistry, dryRunReport, formatReport, resolveTarget, runReport };
+export { REPORTS, defaultReportRegistry, dryRunReport, formatReport, resolveTarget, runReport, runReportResult };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/analysis",
   "type": "module",
-  "version": "0.25.13",
+  "version": "0.26.0",
   "description": "GSC analyzers — striking-distance, opportunity, movers, decay, brand, clustering, concentration, seasonality. Pure row-based + DuckDB-native.",
   "author": {
     "name": "Harlan Wilton",
@@ -41,6 +41,11 @@
       "import": "./dist/source/index.mjs",
       "default": "./dist/source/index.mjs"
     },
+    "./errors": {
+      "types": "./dist/errors.d.mts",
+      "import": "./dist/errors.mjs",
+      "default": "./dist/errors.mjs"
+    },
     "./semantic": {
       "types": "./dist/semantic/index.d.mts",
       "import": "./dist/semantic/index.mjs",
@@ -70,12 +75,12 @@
   },
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
-    "@gscdump/engine-gsc-api": "0.25.13",
-    "@gscdump/engine": "0.25.13",
-    "gscdump": "0.25.13"
+    "@gscdump/engine-gsc-api": "0.26.0",
+    "@gscdump/engine": "0.26.0",
+    "gscdump": "0.26.0"
   },
   "devDependencies": {
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "scripts": {
     "build": "obuild",