@ak--47/dungeon-master 1.4.2 → 1.4.4

package/lib/verify/emulate-breakdown.js

@@ -2,7 +2,7 @@
  * Mixpanel breakdown emulator.
  *
  * Best-effort approximation of the table shapes Mixpanel produces for the five
- * analyses the Phase 4 hook patterns target. Used by `verify-hooks` to assert
+ * analyses the Phase 4 hook patterns target. Used by `verify-dungeon` to assert
  * that engineered patterns actually produce the expected ratios in the data, AND
  * by consumers who want to validate dungeons against expected business shapes
  * outside of Mixpanel.

package/lib/verify/index.js

@@ -10,3 +10,4 @@
 
 export { emulateBreakdown } from './emulate-breakdown.js';
 export { verifyDungeon } from './verify-dungeon.js';
+export { deriveExpectedSchema, validateSchema } from './schema-validator.js';

package/lib/verify/schema-validator.js

@@ -0,0 +1,258 @@
+/**
+ * Schema validation for dungeon output.
+ *
+ * Derives the expected set of property keys per event type from a dungeon
+ * config, then compares against actual output to catch hooks that introduce
+ * undeclared columns ("flag stamping").
+ *
+ * Rule: a hook-introduced column is acceptable (PASS) only if it appears on
+ * 100% of events of that type. Partial coverage is a FAIL.
+ */
+
+/** @typedef {import('../../types.js').Dungeon} Dungeon */
+
+const CORE_KEYS = new Set(['event', 'time', 'insert_id', 'user_id']);
+const LOCATION_KEYS = ['city', 'region', 'country', 'country_code'];
+const DEVICE_KEYS = ['model', 'screen_height', 'screen_width', 'os', 'Platform', 'carrier', 'radio'];
+const CAMPAIGN_KEYS = ['utm_source', 'utm_campaign', 'utm_medium', 'utm_content', 'utm_term'];
+
+/**
+ * Derive the expected property keys per event type from config alone.
+ * @param {Dungeon} config
+ * @returns {Map<string, Set<string>>} eventName → set of expected property keys
+ */
+export function deriveExpectedSchema(config) {
+	const globalKeys = new Set(CORE_KEYS);
+	/** @type {Map<string, Set<string>>} */
+	const perType = new Map();
+
+	if (config.avgDevicePerUser > 0 || config.hasAnonIds) {
+		globalKeys.add('device_id');
+	}
+	if (config.hasSessionIds) {
+		globalKeys.add('session_id');
+	}
+
+	if (config.superProps) {
+		for (const key of Object.keys(config.superProps)) {
+			globalKeys.add(key);
+		}
+	}
+
+	if (config.hasLocation) {
+		for (const k of LOCATION_KEYS) globalKeys.add(k);
+	}
+	if (config.hasBrowser) {
+		globalKeys.add('browser');
+	}
+
+	const hasDevices = config.hasAndroidDevices || config.hasIOSDevices ||
+		config.hasDesktopDevices || (config.avgDevicePerUser && config.avgDevicePerUser > 0);
+	if (hasDevices) {
+		for (const k of DEVICE_KEYS) globalKeys.add(k);
+	}
+
+	if (config.hasCampaigns) {
+		for (const k of CAMPAIGN_KEYS) globalKeys.add(k);
+	}
+
+	if (config.personas) {
+		globalKeys.add('_persona');
+	}
+
+	if (config.dataQuality) {
+		globalKeys.add('_drop');
+	}
+
+	const events = config.events || [];
+	for (const ev of events) {
+		const keys = new Set();
+		if (ev.properties) {
+			for (const k of Object.keys(ev.properties)) {
+				keys.add(k);
+			}
+		}
+		perType.set(ev.event, keys);
+	}
+
+	// Group keys — per event type or global
+	if (config.groupKeys && Array.isArray(config.groupKeys)) {
+		for (const groupPair of config.groupKeys) {
+			const groupKey = groupPair[0];
+			const groupEvents = groupPair[2] || [];
+			if (!groupEvents.length) {
+				globalKeys.add(groupKey);
+			} else {
+				for (const eventName of groupEvents) {
+					ensurePerType(perType, eventName).add(groupKey);
+				}
+			}
+		}
+	}
+
+	// Funnel props — applied to events in funnel sequences
+	if (config.funnels && Array.isArray(config.funnels)) {
+		for (const funnel of config.funnels) {
+			if (funnel.props && Object.keys(funnel.props).length) {
+				const funnelPropKeys = Object.keys(funnel.props);
+				for (const eventName of (funnel.sequence || [])) {
+					if (eventName === '$experiment_started') continue;
+					for (const k of funnelPropKeys) {
+						ensurePerType(perType, eventName).add(k);
+					}
+				}
+			}
+			// $experiment_started event from experiment funnels
+			if (funnel.experiment) {
+				const expKeys = ensurePerType(perType, '$experiment_started');
+				expKeys.add('Experiment name');
+				expKeys.add('Variant name');
+			}
+		}
+	}
+
+	// World event injected props
+	if (config.worldEvents && Array.isArray(config.worldEvents)) {
+		for (const we of config.worldEvents) {
+			if (we.injectProps) {
+				const injectedKeys = Object.keys(we.injectProps);
+				const affects = we.affectsEvents;
+				if (affects === '*') {
+					for (const k of injectedKeys) globalKeys.add(k);
+				} else if (Array.isArray(affects)) {
+					for (const eventName of affects) {
+						for (const k of injectedKeys) {
+							ensurePerType(perType, eventName).add(k);
+						}
+					}
+				}
+			}
+		}
+	}
+
+	// Build final schema: for each event type, merge global + per-type
+	const schema = new Map();
+	for (const [eventName, typeKeys] of perType) {
+		const merged = new Set(globalKeys);
+		for (const k of typeKeys) merged.add(k);
+		schema.set(eventName, merged);
+	}
+
+	// Event types that only appear in funnels but not in events[] config
+	// (e.g. $experiment_started) should still be in the schema
+	for (const [eventName, typeKeys] of perType) {
+		if (!schema.has(eventName)) {
+			const merged = new Set(globalKeys);
+			for (const k of typeKeys) merged.add(k);
+			schema.set(eventName, merged);
+		}
+	}
+
+	return schema;
+}
+
+/**
+ * @typedef {Object} EventTypeReport
+ * @property {string[]} expected
+ * @property {string[]} actual
+ * @property {string[]} added
+ * @property {string[]} missing
+ * @property {Object<string, {count: number, total: number, pct: number}>} coverage
+ * @property {'PASS'|'FAIL'} verdict
+ */
+
+/**
+ * @typedef {Object} SchemaReport
+ * @property {boolean} pass
+ * @property {Object<string, EventTypeReport>} eventTypes
+ * @property {{pass: number, fail: number}} summary
+ * @property {Array<{eventType: string, column: string, coverage: number}>} flagStamping
+ */
+
+/**
+ * Validate generated events against the config-derived schema.
+ * @param {Object[]} events — flat event objects from dungeon output
+ * @param {Dungeon} config — the dungeon config (pre- or post-validation)
+ * @returns {SchemaReport}
+ */
+export function validateSchema(events, config) {
+	const expectedSchema = deriveExpectedSchema(config);
+
+	// Group events by type
+	/** @type {Map<string, Object[]>} */
+	const byType = new Map();
+	for (const ev of events) {
+		const name = ev.event;
+		if (!name) continue;
+		if (!byType.has(name)) byType.set(name, []);
+		byType.get(name).push(ev);
+	}
+
+	/** @type {Object<string, EventTypeReport>} */
+	const eventTypes = {};
+	/** @type {Array<{eventType: string, column: string, coverage: number}>} */
+	const flagStamping = [];
+	let passCount = 0;
+	let failCount = 0;
+
+	for (const [eventName, eventsOfType] of byType) {
+		const expected = expectedSchema.get(eventName) || new Set(CORE_KEYS);
+
+		// Collect all actual keys across events of this type
+		const actualKeys = new Set();
+		for (const ev of eventsOfType) {
+			for (const k of Object.keys(ev)) {
+				actualKeys.add(k);
+			}
+		}
+
+		const expectedArr = Array.from(expected).sort();
+		const actualArr = Array.from(actualKeys).sort();
+		const added = actualArr.filter(k => !expected.has(k));
+		const missing = expectedArr.filter(k => !actualKeys.has(k));
+
+		// Check coverage for added columns
+		/** @type {Object<string, {count: number, total: number, pct: number}>} */
+		const coverage = {};
+		let hasFailure = false;
+		const total = eventsOfType.length;
+
+		for (const col of added) {
+			let count = 0;
+			for (const ev of eventsOfType) {
+				if (ev[col] !== undefined) count++;
+			}
+			const pct = Math.round((count / total) * 10000) / 100;
+			coverage[col] = { count, total, pct };
+			if (pct < 100) {
+				hasFailure = true;
+				flagStamping.push({ eventType: eventName, column: col, coverage: pct });
+			}
+		}
+
+		const verdict = hasFailure ? 'FAIL' : 'PASS';
+		if (verdict === 'PASS') passCount++;
+		else failCount++;
+
+		eventTypes[eventName] = {
+			expected: expectedArr,
+			actual: actualArr,
+			added,
+			missing,
+			coverage,
+			verdict,
+		};
+	}
+
+	return {
+		pass: failCount === 0,
+		eventTypes,
+		summary: { pass: passCount, fail: failCount },
+		flagStamping,
+	};
+}
+
+function ensurePerType(perType, eventName) {
+	if (!perType.has(eventName)) perType.set(eventName, new Set());
+	return perType.get(eventName);
+}

package/lib/verify/verify-dungeon.js

@@ -21,6 +21,7 @@
 
 import DUNGEON_MASTER from '../../index.js';
 import { emulateBreakdown } from './emulate-breakdown.js';
+import { validateSchema } from './schema-validator.js';
 
 /**
  * @typedef {Object} VerifyCheck
@@ -32,7 +33,7 @@ import { emulateBreakdown } from './emulate-breakdown.js';
 /**
  * @param {Object} config - Dungeon config (or path; passed straight to DUNGEON_MASTER).
  * @param {VerifyCheck[]} checks
- * @returns {Promise<{ pass: boolean, results: Array<{ name: string, pass: boolean, detail?: string, rows?: Array<Object> }> }>}
+ * @returns {Promise<{ pass: boolean, results: Array<{ name: string, pass: boolean, detail?: string, rows?: Array<Object> }>, schemaReport: Object }>}
  */
 export async function verifyDungeon(config, checks) {
 	if (!checks || !checks.length) throw new Error('verifyDungeon: at least one check required');
@@ -40,12 +41,12 @@ export async function verifyDungeon(config, checks) {
 	if (Array.isArray(result)) result = result[0];
 	const events = Array.isArray(result.eventData) ? result.eventData : Array.from(result.eventData);
 	const profiles = Array.isArray(result.userProfilesData) ? result.userProfilesData : Array.from(result.userProfilesData);
-	const ctx = { events, profiles };
+	const schemaReport = validateSchema(events, config);
+	const ctx = { events, profiles, schemaReport };
 	const results = [];
 	for (const check of checks) {
 		try {
 			const breakdownArgs = { ...check.breakdown };
-			// timeToConvert + attributedBy may want profiles; auto-inject if not provided.
 			if (breakdownArgs.type === 'timeToConvert' && !breakdownArgs.profiles) {
 				breakdownArgs.profiles = profiles;
 			}
@@ -56,6 +57,6 @@ export async function verifyDungeon(config, checks) {
 			results.push({ name: check.name, pass: false, detail: `error: ${err.message}` });
 		}
 	}
-	const pass = results.every(r => r.pass);
-	return { pass, results };
+	const pass = results.every(r => r.pass) && schemaReport.pass;
+	return { pass, results, schemaReport };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.4.2",
+	"version": "1.4.4",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -26,7 +26,8 @@
 		"scripts/",
 		"package.json",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"HOOKS.md"
 	],
 	"engines": {
 		"node": ">=18.0.0"

package/scripts/verify-runner.mjs

@@ -29,7 +29,7 @@ if (!dungeonPath) {
 	process.exit(1);
 }
 
-const runName = positional[1] || 'verify-hooks';
+const runName = positional[1] || 'verify-dungeon';
 const isSmall = flags.has('--small');
 const absolutePath = path.isAbsolute(dungeonPath)
 	? dungeonPath

package/types.d.ts

@@ -1570,5 +1570,33 @@ export interface EmulateOptions {
 
 declare module '@ak--47/dungeon-master/verify' {
     export function emulateBreakdown(events: EventSchema[], config: EmulateOptions): Array<Record<string, unknown>>;
-    export function verifyDungeon(config: Dungeon, checks: Array<{ name: string; breakdown: EmulateOptions; assert: (rows: Array<Record<string, unknown>>, ctx: { events: EventSchema[]; profiles: UserProfile[] }) => { pass: boolean; detail?: string } }>): Promise<{ pass: boolean; results: Array<{ name: string; pass: boolean; detail?: string; rows?: Array<Record<string, unknown>> }> }>;
+    export function verifyDungeon(config: Dungeon, checks: Array<{ name: string; breakdown: EmulateOptions; assert: (rows: Array<Record<string, unknown>>, ctx: { events: EventSchema[]; profiles: UserProfile[] }) => { pass: boolean; detail?: string } }>): Promise<{ pass: boolean; results: Array<{ name: string; pass: boolean; detail?: string; rows?: Array<Record<string, unknown>> }>; schemaReport: SchemaReport }>;
+    export function deriveExpectedSchema(config: Dungeon): Map<string, Set<string>>;
+    export function validateSchema(events: EventSchema[], config: Dungeon): SchemaReport;
+
+    interface SchemaReport {
+        pass: boolean;
+        eventTypes: Record<string, {
+            expected: string[];
+            actual: string[];
+            added: string[];
+            missing: string[];
+            coverage: Record<string, { count: number; total: number; pct: number }>;
+            verdict: 'PASS' | 'FAIL';
+        }>;
+        summary: { pass: number; fail: number };
+        flagStamping: Array<{ eventType: string; column: string; coverage: number }>;
+    }
+}
+
+declare module '@ak--47/dungeon-master/utils' {
+    export function dateRange(start?: string | number, end?: string | number, format?: string | null): () => string;
+    export function listOf<T>(pool: T[], options?: { min?: number; max?: number }): () => T[];
+    export function objectList(template: Record<string, ValueValid>, options?: { min?: number; max?: number }): () => Array<Record<string, unknown>>;
+    export function weighNumRange(min: number, max: number, skew?: number, size?: number): number[];
+    export function pickAWinner(items: string[], mostChosenIndex?: number): () => string[];
+    export function initChance(seed?: string): unknown;
+    export function TimeSoup(earliestTime: number, latestTime: number, peaks?: number, deviation?: number, mean?: number, dayOfWeekWeights?: number[] | null, hourOfDayWeights?: number[] | null): number;
+    export function weighArray<T>(items: T[]): T[];
+    export function generateUser(user_id: string, opts: Record<string, unknown>): Record<string, unknown>;
 }