@gscdump/engine 0.8.2 → 0.9.0

package/dist/_chunks/index.d.mts

@@ -0,0 +1,57 @@
+import { t as AnalysisParams } from "./analysis-types.mjs";
+type WindowPreset = 'last-7d' | 'last-28d' | 'last-30d' | 'last-90d' | 'last-180d' | 'last-365d' | 'mtd' | 'ytd' | 'custom';
+type ComparisonMode = 'none' | 'prev-period' | 'yoy';
+interface ResolveWindowOptions {
+  preset: WindowPreset;
+  comparison?: ComparisonMode;
+  anchor?: string;
+  start?: string;
+  end?: string;
+}
+interface ResolvedWindow {
+  start: string;
+  end: string;
+  days: number;
+  comparison?: {
+    start: string;
+    end: string;
+  };
+}
+interface AnalysisPeriod {
+  startDate: string;
+  endDate: string;
+}
+interface ComparisonPeriod {
+  current: AnalysisPeriod;
+  previous: AnalysisPeriod;
+}
+declare function defaultEndDate(): string;
+declare function defaultStartDate(): string;
+declare function periodOf(params: AnalysisParams): AnalysisPeriod;
+declare function comparisonOf(params: AnalysisParams): ComparisonPeriod;
+declare function resolveWindow(opts: ResolveWindowOptions): ResolvedWindow;
+/** Convert a ResolvedWindow into the AnalysisPeriod / ComparisonPeriod shape. */
+declare function windowToPeriod(w: ResolvedWindow): AnalysisPeriod;
+declare function windowToComparisonPeriod(w: ResolvedWindow): ComparisonPeriod | undefined;
+interface PadTimeseriesOptions<T> {
+  /** ISO date (YYYY-MM-DD), inclusive lower bound. */
+  startDate: string;
+  /** ISO date (YYYY-MM-DD), inclusive upper bound. */
+  endDate: string;
+  /**
+   * Row to insert for missing dates. Defaults to `{ clicks: 0, impressions: 0, ctr: 0, position: 0 }`.
+   * The `date` field is set automatically.
+   */
+  fill?: Omit<T, 'date'>;
+  /** Row-field that carries the ISO date. Defaults to `date`. */
+  dateKey?: string;
+}
+type DateRowShape = Record<string, unknown> & {
+  date?: unknown;
+};
+/**
+ * Pad rows so every calendar day in `[startDate, endDate]` appears at least
+ * once. Existing dates keep all their rows (grouped timeseries safe).
+ */
+declare function padTimeseries<T extends DateRowShape = DateRowShape>(rows: readonly T[], options: PadTimeseriesOptions<T>): T[];
+export { ResolveWindowOptions as a, comparisonOf as c, padTimeseries as d, periodOf as f, windowToPeriod as h, PadTimeseriesOptions as i, defaultEndDate as l, windowToComparisonPeriod as m, ComparisonMode as n, ResolvedWindow as o, resolveWindow as p, ComparisonPeriod as r, WindowPreset as s, AnalysisPeriod as t, defaultStartDate as u };

package/dist/_chunks/storage.d.mts

@@ -317,6 +317,13 @@ interface QueryExecuteOptions {
    * `dataSource.uri` is available.
    */
   fileKeys: Record<string, string[]>;
+  /**
+   * Per-placeholder table identity. Used by the executor to emit a
+   * schema-correct empty fallback when a named file set is empty: an
+   * `extraFiles` placeholder against `page_keywords` should fall back to
+   * the page_keywords schema, not the analyzer's primary `table`.
+   */
+  placeholderTables?: Record<string, TableName>;
   dataSource: DataSource;
   table: TableName;
   signal?: AbortSignal;

package/dist/index.mjs

@@ -113,18 +113,18 @@ function createDuckDBCodec(factory) {
 		}
 	};
 }
-function rewriteEmptyFileSets(sql, placeholders, table) {
-	const emptyFallback = `(SELECT * FROM ${emptyTableSchema(table)} WHERE FALSE)`;
+function rewriteEmptyFileSets(sql, placeholders, defaultTable, placeholderTables) {
 	let out = sql;
 	for (const [name, keys] of Object.entries(placeholders)) {
 		if (keys.length > 0) continue;
+		const emptyFallback = `(SELECT * FROM ${emptyTableSchema(placeholderTables?.[name] ?? defaultTable)} WHERE FALSE)`;
 		const pattern = new RegExp(`read_parquet\\(\\s*\\{\\{${name}\\}\\}\\s*(?:,\\s*union_by_name\\s*=\\s*true\\s*)?\\)`, "g");
 		out = out.replace(pattern, emptyFallback);
 	}
 	return out;
 }
 function createDuckDBExecutor(factory) {
-	return { async execute({ sql, params, fileKeys, dataSource, table, signal }) {
+	return { async execute({ sql, params, fileKeys, placeholderTables, dataSource, table, signal }) {
 		signal?.throwIfAborted();
 		const db = await factory.getDuckDB();
 		const placeholders = {};
@@ -145,7 +145,7 @@ function createDuckDBExecutor(factory) {
 		}
 		try {
 			signal?.throwIfAborted();
-			const finalSql = substituteNamedFiles(rewriteEmptyFileSets(sql, placeholders, table), placeholders);
+			const finalSql = substituteNamedFiles(rewriteEmptyFileSets(sql, placeholders, table, placeholderTables), placeholders);
 			return {
 				rows: await db.query(finalSql, params),
 				sql: finalSql
@@ -349,10 +349,13 @@ function createStorageEngine(opts) {
 			table = entries[0]?.[1].table;
 		}
 		if (!table) throw new Error("runSQL requires at least one fileSet or an explicit table");
+		const placeholderTables = {};
+		for (const [name, ref] of entries) placeholderTables[name] = ref.table;
 		const result = await executor.execute({
 			sql: opts.sql,
 			params: opts.params ?? [],
 			fileKeys,
+			placeholderTables,
 			dataSource,
 			table,
 			signal: opts.signal

package/dist/period/index.d.mts

@@ -1,57 +1,2 @@
-import { t as AnalysisParams } from "../_chunks/analysis-types.mjs";
-type WindowPreset = 'last-7d' | 'last-28d' | 'last-30d' | 'last-90d' | 'last-180d' | 'last-365d' | 'mtd' | 'ytd' | 'custom';
-type ComparisonMode = 'none' | 'prev-period' | 'yoy';
-interface ResolveWindowOptions {
-  preset: WindowPreset;
-  comparison?: ComparisonMode;
-  anchor?: string;
-  start?: string;
-  end?: string;
-}
-interface ResolvedWindow {
-  start: string;
-  end: string;
-  days: number;
-  comparison?: {
-    start: string;
-    end: string;
-  };
-}
-interface AnalysisPeriod {
-  startDate: string;
-  endDate: string;
-}
-interface ComparisonPeriod {
-  current: AnalysisPeriod;
-  previous: AnalysisPeriod;
-}
-declare function defaultEndDate(): string;
-declare function defaultStartDate(): string;
-declare function periodOf(params: AnalysisParams): AnalysisPeriod;
-declare function comparisonOf(params: AnalysisParams): ComparisonPeriod;
-declare function resolveWindow(opts: ResolveWindowOptions): ResolvedWindow;
-/** Convert a ResolvedWindow into the AnalysisPeriod / ComparisonPeriod shape. */
-declare function windowToPeriod(w: ResolvedWindow): AnalysisPeriod;
-declare function windowToComparisonPeriod(w: ResolvedWindow): ComparisonPeriod | undefined;
-interface PadTimeseriesOptions<T> {
-  /** ISO date (YYYY-MM-DD), inclusive lower bound. */
-  startDate: string;
-  /** ISO date (YYYY-MM-DD), inclusive upper bound. */
-  endDate: string;
-  /**
-   * Row to insert for missing dates. Defaults to `{ clicks: 0, impressions: 0, ctr: 0, position: 0 }`.
-   * The `date` field is set automatically.
-   */
-  fill?: Omit<T, 'date'>;
-  /** Row-field that carries the ISO date. Defaults to `date`. */
-  dateKey?: string;
-}
-type DateRowShape = Record<string, unknown> & {
-  date?: unknown;
-};
-/**
- * Pad rows so every calendar day in `[startDate, endDate]` appears at least
- * once. Existing dates keep all their rows (grouped timeseries safe).
- */
-declare function padTimeseries<T extends DateRowShape = DateRowShape>(rows: readonly T[], options: PadTimeseriesOptions<T>): T[];
+import { a as ResolveWindowOptions, c as comparisonOf, d as padTimeseries, f as periodOf, h as windowToPeriod, i as PadTimeseriesOptions, l as defaultEndDate, m as windowToComparisonPeriod, n as ComparisonMode, o as ResolvedWindow, p as resolveWindow, r as ComparisonPeriod, s as WindowPreset, t as AnalysisPeriod, u as defaultStartDate } from "../_chunks/index.mjs";
 export { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, defaultEndDate, defaultStartDate, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod };

package/dist/report/index.d.mts

@@ -0,0 +1,171 @@
+import { n as AnalysisResult, t as AnalysisParams } from "../_chunks/analysis-types.mjs";
+import { n as ComparisonMode, o as ResolvedWindow, s as 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;
+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

@@ -0,0 +1,56 @@
+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()]
+	};
+}
+export { canonicalize, computeInputHash, createReportRegistry, defineReport };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine",
   "type": "module",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Append-only Parquet/DuckDB storage engine + planner + adapters for the gscdump pipeline. Node + edge runtimes; opt-in heavy peers.",
   "author": {
     "name": "Harlan Wilton",
@@ -101,6 +101,11 @@
       "import": "./dist/analyzer/index.mjs",
       "default": "./dist/analyzer/index.mjs"
     },
+    "./report": {
+      "types": "./dist/report/index.d.mts",
+      "import": "./dist/report/index.mjs",
+      "default": "./dist/report/index.mjs"
+    },
     "./analysis-types": {
       "types": "./dist/analysis-types.d.mts",
       "import": "./dist/analysis-types.mjs",
@@ -154,7 +159,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "proper-lockfile": "^4.1.2",
-    "gscdump": "0.8.2"
+    "gscdump": "0.9.0"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",