@gscdump/engine 1.4.0 → 1.4.1

package/dist/report/index.d.mts

@@ -1,171 +1,5 @@
-import { AnalysisParams, AnalysisResult } from "../_chunks/analysis-types.mjs";
-import { ComparisonMode, ResolvedWindow, WindowPreset } from "../_chunks/index.mjs";
-/** Status vocabulary mirrors `ActionPrioritySourceStatus`. */
-type ReportStepStatus = 'pending' | 'running' | 'done' | 'skipped' | 'error';
-type ReportSeverity = 'info' | 'low' | 'medium' | 'high';
-type ReportEntityKind = 'page' | 'query';
-type ReportActionKind = 'analyzer' | 'cli' | 'indexing' | 'fix';
-type ReportCoverage = 'full' | 'partial';
-/** Citty-shaped arg spec, kept structural so engine doesn't pull citty in. */
-interface ReportArgDef {
-  type: 'string' | 'boolean' | 'number';
-  description?: string;
-  default?: string | boolean | number;
-  required?: boolean;
-  alias?: string;
-}
-type ReportArgsSpec = Record<string, ReportArgDef>;
-interface ReportEntity {
-  kind: ReportEntityKind;
-  value: string;
-}
-interface ReportFindingDelta {
-  metric: string;
-  prior: number;
-  current: number;
-  pct: number;
-}
-interface ReportFinding {
-  entity: ReportEntity;
-  metrics: Record<string, number>;
-  delta?: ReportFindingDelta;
-  why?: string;
-}
-interface ReportSectionSummary {
-  delta?: number;
-  direction?: 'up' | 'down' | 'flat';
-  magnitudeLabel?: string;
-}
-interface ReportAction {
-  kind: ReportActionKind;
-  target?: ReportEntity;
-  params?: Record<string, unknown>;
-  rationale: string;
-  /** Human hint, generated; never authoritative. */
-  cliHint?: string;
-}
-interface ReportSectionArtifact {
-  analyzer: string;
-  params: AnalysisParams;
-}
-interface ReportSection {
-  id: string;
-  title: string;
-  severity: ReportSeverity;
-  summary: ReportSectionSummary;
-  /** Bounded; sorted by stable composite key. */
-  findings: ReportFinding[];
-  truncated?: {
-    kept: number;
-    total: number;
-  };
-  coverage: ReportCoverage;
-  actions: ReportAction[];
-  artifact?: ReportSectionArtifact;
-}
-interface ReportPlanStep {
-  /** Stable identifier within the report (e.g. `movers`, `decay-current`). */
-  key: string;
-  /** Analyzer id (or future: nested report id). Open string by design. */
-  type: string;
-  /** Analyzer params; report-runtime applies `type` from the step. */
-  params: Omit<AnalysisParams, 'type'>;
-  /** Required steps fail the report; optional steps degrade `coverage`. */
-  required?: boolean;
-}
-interface ReportStepStateMeta {
-  key: string;
-  type: string;
-  status: ReportStepStatus;
-  error?: string;
-}
-interface ReportResultMeta {
-  durationMs: number;
-  rowsScanned: number;
-  degraded: boolean;
-  steps: ReportStepStateMeta[];
-}
-interface ReportResult {
-  id: string;
-  site: string;
-  /** sha256(id|site|window|paramsCanonical|registryVersion). Stable. */
-  inputHash: string;
-  /** ISO 8601. NOT included in inputHash. */
-  generatedAt: string;
-  window: ResolvedWindow;
-  sections: ReportSection[];
-  meta: ReportResultMeta;
-}
-/**
- * Loose params bag. Concrete reports refine this with their own interface.
- * Constraint is `object` so report authors can use plain interfaces without
- * needing an index signature.
- */
-type ReportParams = object;
-interface ReportContext<P extends ReportParams = ReportParams> {
-  /** Resolved site URL (e.g. `https://example.com/`). */
-  site: string;
-  /** Already-resolved window — runtime calls `resolveWindow` once before plan(). */
-  window: ResolvedWindow;
-  params: P;
-  /** Hash of registry/code version. Bumped via package version. */
-  registryVersion: string;
-}
-/**
- * Reduce step results → sections. Runtime injects `meta` post-reduce.
- */
-type ReportReducer<P extends ReportParams = ReportParams> = (results: Record<string, AnalysisResult>, ctx: ReportContext<P>) => Omit<ReportResult, 'meta' | 'inputHash' | 'generatedAt' | 'site' | 'window' | 'id'> & {
-  sections: ReportSection[];
-};
-interface DefinedReport<P extends ReportParams = ReportParams> {
-  id: string;
-  description: string;
-  defaultPeriod: WindowPreset;
-  defaultComparison: ComparisonMode;
-  /** Single source of truth for CLI flags + MCP input schema. */
-  argsSpec: ReportArgsSpec;
-  plan: (params: P, window: ResolvedWindow) => readonly ReportPlanStep[];
-  reduce: ReportReducer<P>;
-}
-interface DefineReportOptions<P extends ReportParams = ReportParams> {
-  id: string;
-  description: string;
-  defaultPeriod: WindowPreset;
-  defaultComparison: ComparisonMode;
-  argsSpec?: ReportArgsSpec;
-  plan: (params: P, window: ResolvedWindow) => readonly ReportPlanStep[];
-  reduce: ReportReducer<P>;
-}
-/**
- * Mirror of `defineAnalyzer`. Pure factory: validates required fields,
- * fills default `argsSpec`. No runtime behaviour — `runReport` consumes
- * the returned object.
- */
-declare function defineReport<P extends ReportParams = ReportParams>(opts: DefineReportOptions<P>): DefinedReport<P>;
-interface InputHashSeeds {
-  id: string;
-  site: string;
-  window: ResolvedWindow;
-  params: ReportParams;
-  registryVersion: string;
-}
-/** Stable JSON: sorts object keys at every level. Arrays preserve order. */
-declare function canonicalize(value: unknown): unknown;
-declare function computeInputHash(seeds: InputHashSeeds): Promise<string>;
-interface ReportRegistryInit {
-  reports?: readonly DefinedReport<ReportParams>[];
-  /**
-   * Opaque version string. Used as the `registryVersion` input to
-   * `inputHash` so cached results invalidate when report code ships.
-   * Caller is expected to feed in their package version.
-   */
-  version?: string;
-}
-interface ReportRegistry {
-  version: string;
-  listReportIds: () => readonly string[];
-  getReport: (id: string) => DefinedReport<ReportParams> | undefined;
-  listReports: () => readonly DefinedReport<ReportParams>[];
-}
-declare function createReportRegistry(init?: ReportRegistryInit): ReportRegistry;
+import { DefineReportOptions, DefinedReport, ReportAction, ReportActionKind, ReportArgDef, ReportArgsSpec, ReportContext, ReportCoverage, ReportEntity, ReportEntityKind, ReportFinding, ReportFindingDelta, ReportParams, ReportPlanStep, ReportReducer, ReportResult, ReportResultMeta, ReportSection, ReportSectionArtifact, ReportSectionSummary, ReportSeverity, ReportStepStateMeta, ReportStepStatus } from "./types.mjs";
+import { defineReport } from "./define.mjs";
+import { InputHashSeeds, canonicalize, computeInputHash } from "./hash.mjs";
+import { ReportRegistry, ReportRegistryInit, createReportRegistry } from "./registry.mjs";
 export { type DefineReportOptions, type DefinedReport, type InputHashSeeds, type ReportAction, type ReportActionKind, type ReportArgDef, type ReportArgsSpec, type ReportContext, type ReportCoverage, type ReportEntity, type ReportEntityKind, type ReportFinding, type ReportFindingDelta, type ReportParams, type ReportPlanStep, type ReportReducer, type ReportRegistry, type ReportRegistryInit, type ReportResult, type ReportResultMeta, type ReportSection, type ReportSectionArtifact, type ReportSectionSummary, type ReportSeverity, type ReportStepStateMeta, type ReportStepStatus, canonicalize, computeInputHash, createReportRegistry, defineReport };

package/dist/report/index.mjs

@@ -1,56 +1,4 @@
-function defineReport(opts) {
-	if (!opts.id) throw new Error("defineReport: id is required");
-	if (!opts.plan) throw new Error(`defineReport(${opts.id}): plan is required`);
-	if (!opts.reduce) throw new Error(`defineReport(${opts.id}): reduce is required`);
-	return {
-		id: opts.id,
-		description: opts.description,
-		defaultPeriod: opts.defaultPeriod,
-		defaultComparison: opts.defaultComparison,
-		argsSpec: opts.argsSpec ?? {},
-		plan: opts.plan,
-		reduce: opts.reduce
-	};
-}
-function canonicalize(value) {
-	if (value == null || typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map(canonicalize);
-	const out = {};
-	for (const k of Object.keys(value).sort()) out[k] = canonicalize(value[k]);
-	return out;
-}
-async function computeInputHash(seeds) {
-	const payload = JSON.stringify(canonicalize({
-		id: seeds.id,
-		site: seeds.site,
-		window: {
-			start: seeds.window.start,
-			end: seeds.window.end,
-			comparison: seeds.window.comparison ?? null
-		},
-		params: seeds.params,
-		registryVersion: seeds.registryVersion
-	}));
-	const bytes = new TextEncoder().encode(payload);
-	return bufferToHex(await globalThis.crypto.subtle.digest("SHA-256", bytes));
-}
-function bufferToHex(buffer) {
-	const bytes = new Uint8Array(buffer);
-	let out = "";
-	for (let i = 0; i < bytes.length; i++) out += bytes[i].toString(16).padStart(2, "0");
-	return out;
-}
-function createReportRegistry(init = {}) {
-	const byId = /* @__PURE__ */ new Map();
-	for (const r of init.reports ?? []) {
-		if (byId.has(r.id)) throw new Error(`createReportRegistry: duplicate report id ${r.id}`);
-		byId.set(r.id, r);
-	}
-	return {
-		version: init.version ?? "0",
-		listReportIds: () => [...byId.keys()].sort(),
-		getReport: (id) => byId.get(id),
-		listReports: () => [...byId.values()]
-	};
-}
+import { defineReport } from "./define.mjs";
+import { canonicalize, computeInputHash } from "./hash.mjs";
+import { createReportRegistry } from "./registry.mjs";
 export { canonicalize, computeInputHash, createReportRegistry, defineReport };

package/dist/report/registry.d.mts

@@ -0,0 +1,18 @@
+import { DefinedReport, ReportParams } from "./types.mjs";
+interface ReportRegistryInit {
+  reports?: readonly DefinedReport<ReportParams>[];
+  /**
+   * Opaque version string. Used as the `registryVersion` input to
+   * `inputHash` so cached results invalidate when report code ships.
+   * Caller is expected to feed in their package version.
+   */
+  version?: string;
+}
+interface ReportRegistry {
+  version: string;
+  listReportIds: () => readonly string[];
+  getReport: (id: string) => DefinedReport<ReportParams> | undefined;
+  listReports: () => readonly DefinedReport<ReportParams>[];
+}
+declare function createReportRegistry(init?: ReportRegistryInit): ReportRegistry;
+export { ReportRegistry, ReportRegistryInit, createReportRegistry };

package/dist/report/registry.mjs

@@ -0,0 +1,14 @@
+function createReportRegistry(init = {}) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const r of init.reports ?? []) {
+		if (byId.has(r.id)) throw new Error(`createReportRegistry: duplicate report id ${r.id}`);
+		byId.set(r.id, r);
+	}
+	return {
+		version: init.version ?? "0",
+		listReportIds: () => [...byId.keys()].sort(),
+		getReport: (id) => byId.get(id),
+		listReports: () => [...byId.values()]
+	};
+}
+export { createReportRegistry };

package/dist/report/types.d.mts

@@ -0,0 +1,139 @@
+import { AnalysisParams, AnalysisResult } from "../analysis-types.mjs";
+import { ComparisonMode, ResolvedWindow, WindowPreset } from "../period/index.mjs";
+/** Status vocabulary mirrors `ActionPrioritySourceStatus`. */
+type ReportStepStatus = 'pending' | 'running' | 'done' | 'skipped' | 'error';
+type ReportSeverity = 'info' | 'low' | 'medium' | 'high';
+type ReportEntityKind = 'page' | 'query';
+type ReportActionKind = 'analyzer' | 'cli' | 'indexing' | 'fix';
+type ReportCoverage = 'full' | 'partial';
+/** Citty-shaped arg spec, kept structural so engine doesn't pull citty in. */
+interface ReportArgDef {
+  type: 'string' | 'boolean' | 'number';
+  description?: string;
+  default?: string | boolean | number;
+  required?: boolean;
+  alias?: string;
+}
+type ReportArgsSpec = Record<string, ReportArgDef>;
+interface ReportEntity {
+  kind: ReportEntityKind;
+  value: string;
+}
+interface ReportFindingDelta {
+  metric: string;
+  prior: number;
+  current: number;
+  pct: number;
+}
+interface ReportFinding {
+  entity: ReportEntity;
+  metrics: Record<string, number>;
+  delta?: ReportFindingDelta;
+  why?: string;
+}
+interface ReportSectionSummary {
+  delta?: number;
+  direction?: 'up' | 'down' | 'flat';
+  magnitudeLabel?: string;
+}
+interface ReportAction {
+  kind: ReportActionKind;
+  target?: ReportEntity;
+  params?: Record<string, unknown>;
+  rationale: string;
+  /** Human hint, generated; never authoritative. */
+  cliHint?: string;
+}
+interface ReportSectionArtifact {
+  analyzer: string;
+  params: AnalysisParams;
+}
+interface ReportSection {
+  id: string;
+  title: string;
+  severity: ReportSeverity;
+  summary: ReportSectionSummary;
+  /** Bounded; sorted by stable composite key. */
+  findings: ReportFinding[];
+  truncated?: {
+    kept: number;
+    total: number;
+  };
+  coverage: ReportCoverage;
+  actions: ReportAction[];
+  artifact?: ReportSectionArtifact;
+}
+interface ReportPlanStep {
+  /** Stable identifier within the report (e.g. `movers`, `decay-current`). */
+  key: string;
+  /** Analyzer id (or future: nested report id). Open string by design. */
+  type: string;
+  /** Analyzer params; report-runtime applies `type` from the step. */
+  params: Omit<AnalysisParams, 'type'>;
+  /** Required steps fail the report; optional steps degrade `coverage`. */
+  required?: boolean;
+}
+interface ReportStepStateMeta {
+  key: string;
+  type: string;
+  status: ReportStepStatus;
+  error?: string;
+}
+interface ReportResultMeta {
+  durationMs: number;
+  rowsScanned: number;
+  degraded: boolean;
+  steps: ReportStepStateMeta[];
+}
+interface ReportResult {
+  id: string;
+  site: string;
+  /** sha256(id|site|window|paramsCanonical|registryVersion). Stable. */
+  inputHash: string;
+  /** ISO 8601. NOT included in inputHash. */
+  generatedAt: string;
+  window: ResolvedWindow;
+  sections: ReportSection[];
+  meta: ReportResultMeta;
+}
+/**
+ * Loose params bag. Concrete reports refine this with their own interface.
+ * Constraint is `object` so report authors can use plain interfaces without
+ * needing an index signature.
+ */
+type ReportParams = object;
+interface ReportContext<P extends ReportParams = ReportParams> {
+  /** Resolved site URL (e.g. `https://example.com/`). */
+  site: string;
+  /** Already-resolved window — runtime calls `resolveWindow` once before plan(). */
+  window: ResolvedWindow;
+  params: P;
+  /** Hash of registry/code version. Bumped via package version. */
+  registryVersion: string;
+}
+/**
+ * Reduce step results → sections. Runtime injects `meta` post-reduce.
+ */
+type ReportReducer<P extends ReportParams = ReportParams> = (results: Record<string, AnalysisResult>, ctx: ReportContext<P>) => Omit<ReportResult, 'meta' | 'inputHash' | 'generatedAt' | 'site' | 'window' | 'id'> & {
+  sections: ReportSection[];
+};
+interface DefinedReport<P extends ReportParams = ReportParams> {
+  id: string;
+  description: string;
+  defaultPeriod: WindowPreset;
+  defaultComparison: ComparisonMode;
+  /** Single source of truth for CLI flags + MCP input schema. */
+  argsSpec: ReportArgsSpec;
+  plan: (params: P, window: ResolvedWindow) => readonly ReportPlanStep[];
+  reduce: ReportReducer<P>;
+}
+interface DefineReportOptions<P extends ReportParams = ReportParams> {
+  id: string;
+  description: string;
+  defaultPeriod: WindowPreset;
+  defaultComparison: ComparisonMode;
+  argsSpec?: ReportArgsSpec;
+  plan: (params: P, window: ResolvedWindow) => readonly ReportPlanStep[];
+  reduce: ReportReducer<P>;
+}
+export { DefineReportOptions, DefinedReport, ReportAction, ReportActionKind, ReportArgDef, ReportArgsSpec, ReportContext, ReportCoverage, ReportEntity, ReportEntityKind, ReportFinding, ReportFindingDelta, ReportParams, ReportPlanStep, ReportReducer, ReportResult, ReportResultMeta, ReportSection, ReportSectionArtifact, ReportSectionSummary, ReportSeverity, ReportStepStateMeta, ReportStepStatus };

package/dist/resolver/adapter.d.mts

@@ -0,0 +1,13 @@
+import { ResolverAdapter } from "./types.mjs";
+import { SqlFragmentsConfig } from "./fragments.mjs";
+import { PlannerCapabilities } from "gscdump/query/plan";
+import { SQL } from "drizzle-orm";
+interface CreateResolverAdapterConfig<TableKey extends string> extends SqlFragmentsConfig<TableKey> {
+  compile: (query: SQL) => {
+    sql: string;
+    params: unknown[];
+  };
+  capabilities: PlannerCapabilities;
+}
+declare function createResolverAdapter<TableKey extends string>(config: CreateResolverAdapterConfig<TableKey>): ResolverAdapter<TableKey>;
+export { CreateResolverAdapterConfig, createResolverAdapter };

package/dist/resolver/adapter.mjs

@@ -0,0 +1,27 @@
+import { createSqlFragments } from "./fragments.mjs";
+function createResolverAdapter(config) {
+	const runtime = createSqlFragments(config);
+	return {
+		METRIC_NAMES: runtime.METRIC_NAMES,
+		capabilities: config.capabilities,
+		schema: config.schema,
+		tableKeyForDataset: runtime.tableKeyForDataset,
+		inferTable: runtime.inferTable,
+		dimColumn: runtime.dimColumn,
+		isMetricDimension: runtime.isMetricDimension,
+		tableRef: runtime.tableRef,
+		fromSql: runtime.fromSql,
+		dateColRef: runtime.dateColRef,
+		urlToPathExpr: runtime.urlToPathExpr,
+		siteIdColRef: runtime.siteIdColRef,
+		searchTypeColRef: runtime.searchTypeColRef,
+		dimExprSql: runtime.dimExprSql,
+		metricSql: runtime.metricSql,
+		dimensionPredicates: runtime.dimensionPredicates,
+		havingPredicates: runtime.havingPredicates,
+		prefilterPredicates: runtime.prefilterPredicates,
+		topLevelPredicate: runtime.topLevelPredicate,
+		compile: config.compile
+	};
+}
+export { createResolverAdapter };

package/dist/resolver/canonical-source.d.mts

@@ -0,0 +1,5 @@
+import { PlannerCapabilities } from "gscdump/query/plan";
+import { BuilderState } from "gscdump/query";
+/** State-level convenience: build the plan then gate. */
+declare function canonicalRollupCovers(state: BuilderState, capabilities: PlannerCapabilities): boolean;
+export { canonicalRollupCovers };

package/dist/resolver/canonical-source.mjs

@@ -0,0 +1,14 @@
+import { buildLogicalPlan } from "gscdump/query/plan";
+const ALLOWED_FILTER_DIMS = /* @__PURE__ */ new Set(["date", "queryCanonical"]);
+function planCoveredByCanonicalRollup(plan) {
+	if (plan.dataset !== "queries") return false;
+	if (plan.groupByDimensions.length !== 1 || plan.groupByDimensions[0] !== "queryCanonical") return false;
+	if (!plan.dimensionFilters.every((f) => ALLOWED_FILTER_DIMS.has(f.dimension))) return false;
+	if (plan.prefilters.length > 0) return false;
+	if (plan.specialFilters.topLevel) return false;
+	return true;
+}
+function canonicalRollupCovers(state, capabilities) {
+	return planCoveredByCanonicalRollup(buildLogicalPlan(state, capabilities));
+}
+export { canonicalRollupCovers };

package/dist/resolver/compile.d.mts

@@ -0,0 +1,15 @@
+import { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverOptions } from "./types.mjs";
+import { BuilderState } from "gscdump/query";
+declare function resolveToSQLOptimized<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQLOptimized;
+declare function resolveToSQL<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQL;
+declare function buildTotalsSql<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): {
+  sql: string;
+  params: unknown[];
+};
+declare function resolveComparisonSQL<TK extends string>(current: BuilderState, previous: BuilderState, options: ResolverOptions<TK>, comparisonFilter?: ComparisonFilter): ResolvedComparisonSQL;
+declare function buildExtrasQueries<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ExtraQuery[];
+declare function mergeExtras(rows: Record<string, unknown>[], extrasResults: {
+  key: string;
+  results: Record<string, unknown>[];
+}[]): Record<string, unknown>[];
+export { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized };