@gscdump/analysis 0.8.2 → 0.9.1

package/dist/report/index.d.mts

@@ -0,0 +1,71 @@
+import * as _$_gscdump_engine_report0 from "@gscdump/engine/report";
+import { DefinedReport, ReportContext, ReportParams, ReportResult } from "@gscdump/engine/report";
+import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
+import { AnalysisQuerySource } from "@gscdump/engine/resolver";
+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: _$_gscdump_engine_report0.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>;
+}
+/**
+ * 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<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 { type DryRunReportResult, type FormatReportOptions, REPORTS, type ResolveTargetInput, type ResolveTargetKind, type ResolveTargetResult, type RunReportOptions, defaultReportRegistry, dryRunReport, formatReport, resolveTarget, runReport };