@gscdump/analysis 1.0.1 → 1.0.3

package/dist/_chunks/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/_chunks/index.d.mts

@@ -0,0 +1,89 @@
+import { AnalysisError } from "./errors.mjs";
+import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
+import { Result } from "gscdump/result";
+import { AnalysisQuerySource } from "@gscdump/engine/source";
+import { DefinedReport, ReportContext, ReportParams, ReportResult } from "@gscdump/engine/report";
+interface FormatReportOptions {
+  /** Cap findings rendered per section. Defaults to all (already bounded by report). */
+  maxFindingsPerSection?: number;
+}
+declare function formatReport(report: ReportResult, opts?: FormatReportOptions): string;
+declare const REPORTS: readonly DefinedReport<ReportParams>[];
+declare const defaultReportRegistry: import("@gscdump/engine/report").ReportRegistry;
+/**
+ * `resolveTarget()` — stub day-one resolver. Future versions can wire in
+ * fuzzy matching / embedding similarity / a manifest cache without
+ * changing the contract.
+ *
+ * Today: case-insensitive exact match, falling back to substring (LIKE %x%)
+ * over a caller-supplied candidate list.
+ */
+type ResolveTargetKind = 'page' | 'query';
+interface ResolveTargetInput {
+  kind: ResolveTargetKind;
+  input: string;
+  /**
+   * Pool to resolve against. Empty pool ⇒ caller trusts the input verbatim
+   * (resolver returns it as `exact`). Useful when the caller doesn't have
+   * a candidate list yet but knows the value is correct.
+   */
+  candidates?: readonly string[];
+}
+interface ResolveTargetResult {
+  /** Best exact match from `candidates` (case-insensitive), or trusted input when no candidates were supplied. */
+  exact: string | null;
+  /** All candidates that include the input as a substring (case-insensitive). Includes `exact` if matched. */
+  matches: string[];
+  /** True when no candidates matched at all. */
+  unresolved: boolean;
+}
+declare function resolveTarget(opts: ResolveTargetInput): ResolveTargetResult;
+interface RunReportOptions<P extends ReportParams = ReportParams> {
+  source: AnalysisQuerySource;
+  analyzers: AnalyzerRegistry;
+  ctx: ReportContext<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<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 {
+  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<P>, ctx: ReportContext<P>): Promise<DryRunReportResult>;
+export { DryRunReportResult, FormatReportOptions, REPORTS, ResolveTargetInput, ResolveTargetKind, ResolveTargetResult, RunReportOptions, defaultReportRegistry, dryRunReport, formatReport, resolveTarget, runReport, runReportResult };

package/dist/_chunks/index2.d.mts

@@ -0,0 +1,37 @@
+import { BuilderState } from "gscdump/query";
+import { AnalysisQuerySource, QueryRow } from "@gscdump/engine/source";
+import { PlannerCapabilities } from "gscdump/query/plan";
+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;
+  live: AnalysisQuerySource;
+  site: SyncedRange;
+}
+declare function createCompositeSource(opts: CompositeSourceOptions): AnalysisQuerySource;
+/**
+ * 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[]> | QueryRow[];
+  capabilities?: PlannerCapabilities;
+}
+declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): AnalysisQuerySource;
+export { CompositeSourceOptions, IN_MEMORY_DEFAULT_CAPABILITIES, InMemoryQuerySourceOptions, SyncedRange, createCompositeSource, createInMemoryQuerySource };