@gscdump/analysis 0.4.0

package/dist/default-registry.d.mts

@@ -0,0 +1,93 @@
+import { BuilderState } from "gscdump/query";
+import { Row } from "@gscdump/engine/contracts";
+import { FileSet } from "@gscdump/engine/resolver";
+import { AnalysisParams } from "gscdump/contracts";
+/**
+ * Capabilities a Plan may require of its host. A dispatcher matches these
+ * against a source's declared capabilities and rejects mismatches.
+ */
+type Capability = 'executeSql' | 'partitionedParquet' | 'attachedTables' | 'regex' | 'windowTotals' | 'comparisonJoin';
+interface SqlExtraQuery {
+  name: string;
+  sql: string;
+  params: unknown[];
+}
+/**
+ * SQL-native plan: SQL string + placeholders, with optional extra file sets
+ * and follow-up queries. Mirrors the existing `AnalyzerSpec` shape but
+ * renamed for clarity under the unified contract.
+ */
+interface SqlPlan {
+  kind: 'sql';
+  sql: string;
+  params: unknown[];
+  current: FileSet;
+  previous?: FileSet;
+  extraFiles?: Record<string, FileSet>;
+  extraQueries?: SqlExtraQuery[];
+  /** Emits direct table refs (browser-only). Dispatcher rejects for manifest path. */
+  requiresAttachedTables?: boolean;
+}
+interface TypedRowQuery<T extends Row = Row> {
+  state: BuilderState;
+  /** Optional type tag for downstream narrowing. */
+  rowType?: (row: Row) => T;
+}
+/**
+ * Row-queries plan: a named set of typed `BuilderState` queries. A portable
+ * dispatcher runs each against a source's `queryRows` and hands the row
+ * collection to `reduce`.
+ */
+interface RowQueriesPlan {
+  kind: 'rows';
+  queries: Record<string, TypedRowQuery>;
+}
+type Plan = SqlPlan | RowQueriesPlan;
+interface ReduceContext<TRow extends Row = Row> {
+  params: AnalysisParams;
+  /** Extra SQL-query results keyed by `SqlExtraQuery.name`. */
+  extras?: Record<string, TRow[]>;
+}
+/**
+ * Unified analyzer contract. `TRow` lets authors narrow from the default
+ * `Row = Record<string, unknown>` to a typed row shape (e.g. `KeywordRow`)
+ * when their reducer assumes specific columns exist — catches drift between
+ * `build` (SELECT list) and `reduce` (column access) at compile time.
+ */
+interface Analyzer<P extends AnalysisParams = AnalysisParams, R = unknown, TRow extends Row = Row> {
+  /** Stable tool id (e.g. `striking-distance`, `opportunity`). */
+  id: string;
+  /** Capabilities a host source must provide. */
+  requires: readonly Capability[];
+  /** Pure: params → plan. Snapshot-testable. */
+  build: (params: P) => Plan;
+  /** Pure: rows + context → typed result + meta. */
+  reduce: (rows: TRow[] | Record<string, TRow[]>, ctx: ReduceContext<TRow>) => {
+    results: R;
+    meta?: Record<string, unknown>;
+  };
+}
+interface AnalyzerVariants {
+  sql?: Analyzer;
+  rows?: Analyzer;
+}
+interface AnalyzerRegistry {
+  listAnalyzerIds: () => readonly string[];
+  getAnalyzerVariants: (id: string) => AnalyzerVariants | undefined;
+  resolveAnalyzer: (id: string, sourceSupportsSql: boolean) => Analyzer | undefined;
+  listAnalyzersFor: (sourceSupportsSql: boolean) => readonly Analyzer[];
+  listAnalyzerIdsFor: (source: {
+    executeSql?: unknown;
+  }) => readonly string[];
+}
+/**
+ * Default analyzer registry built from every in-tree analyzer: row analyzers
+ * plus DuckDB SQL analyzers. Convenience for callers who don't care about
+ * bundle size; edge / browser consumers should compose their own narrower
+ * registry via `createAnalyzerRegistry`.
+ *
+ * Importing this module transitively pulls in `@gscdump/engine-duckdb-node`
+ * and its DuckDB SQL builder code.
+ */
+declare const defaultAnalyzerRegistry: AnalyzerRegistry;
+export { defaultAnalyzerRegistry };