cyborg-hunter 0.3.0

package/src/cli/ingest.js

@@ -0,0 +1,343 @@
+// src/cli/ingest.js
+// Loads JSON or CSV data files, extracts integrity data, validates schema.
+//
+// Handles three input pathways:
+//   1. JSON, Shape 1 — one file per participant with a trials array containing
+//      an integrity sub-object: { participantId: 'P1', trials: [{ integrity: {...} }] }
+//   2. JSON, Shape 2 — rule-gallery format: { metadata: { subjectId: 'P1' },
+//      responses: [{ mouseTrack: [...], tabAwayEvents: [...] }] }
+//   3. CSV — jsPsych default save format. Each row is a trial; nested objects
+//      (integrity, integritySession, integrityScore) are JSON-stringified into
+//      single cells by Papa Parse's unparse. We unwrap them back into objects,
+//      then route through Shape 1.
+//
+// Legacy field names (mouseTrack) are mapped to CyborgHunter schema names (mouseEvents).
+
+import { readFileSync, readdirSync } from 'fs';
+import { join, extname } from 'path';
+import Papa from 'papaparse';
+import { TRIAL_REPORT_FIELDS } from '../shared/schema.js';
+
+export async function ingest(config) {
+  const files = findFiles(config.dataDir, config.filePattern);
+  const participants = [];
+  const warnings = [];
+
+  for (const file of files) {
+    try {
+      const text = readFileSync(file, 'utf8');
+      // Branch by extension. CSV is jsPsych's default save format; JSON is what
+      // rule-gallery and other server-side-saving experiments use.
+      const raw = extname(file).toLowerCase() === '.csv'
+        ? parseCsvToRaw(text, config)
+        : JSON.parse(text);
+      const result = extractIntegrityData(raw, config);
+
+      // --participant flag filters to a single participant
+      if (config.singleParticipant && result.participantId !== config.singleParticipant) {
+        continue;
+      }
+
+      if (result.warnings.length > 0) {
+        warnings.push({ file, warnings: result.warnings });
+      }
+      if (result.trials.length > 0) {
+        participants.push(result);
+      }
+    } catch (e) {
+      warnings.push({ file, warnings: [`Failed to parse: ${e.message}`] });
+    }
+  }
+
+  return { participants, warnings };
+}
+
+// Extracts integrity trial data from a single participant's raw JSON.
+// Returns { participantId, trials, warnings, metadata }.
+export function extractIntegrityData(raw, config) {
+  const warnings = [];
+  const pidField = config.participantIdField || 'participantId';
+  const intField = config.integrityField || 'integrity';
+
+  // Determine participant ID — check top level, then metadata sub-object
+  const participantId = raw[pidField] || raw.metadata?.[pidField] || 'unknown';
+
+  let trials = [];
+
+  // Shape 1: { trials: [{ integrity: {...} }, ...] }
+  // Each trial has an `integrity` sub-object added by CyborgHunter's endTrial()
+  if (Array.isArray(raw.trials)) {
+    trials = raw.trials
+      .filter(t => t[intField])
+      .map(t => t[intField]);
+    // P3: jsPsych extension data carries trialStart_perfNow on every trial
+    // (set by the wrapper's on_load), so the fast path subtracts directly
+    // and gives exact trial-relative startRel_ms. Without this, renderers
+    // see only session-absolute `start` and plot tab-away markers off-canvas.
+    normalizeTabAwayTimestamps(trials, raw);
+  }
+  // Shape 2: { responses: [{ mouseTrack, tabAwayEvents, ... }] } (rule-gallery legacy format)
+  // Signal data lives directly on the response — no integrity wrapper.
+  // We apply field name mapping (mouseTrack → mouseEvents).
+  else if (Array.isArray(raw.responses)) {
+    trials = raw.responses.map((r, i) => mapLegacyFields({
+      ...r,
+      _sourceIndex: i
+    }));
+    // Normalize tab-away timestamps from session-relative performance.now()
+    // to trial-relative milliseconds so renderers can plot them on the
+    // same x-axis as mouseEvents[].t (which is already trial-relative).
+    normalizeTabAwayTimestamps(trials, raw);
+  }
+  // Shape 3: Top-level array of trials
+  else if (Array.isArray(raw)) {
+    trials = raw.filter(t => t[intField]).map(t => t[intField]);
+  }
+
+  if (trials.length === 0) {
+    warnings.push(`No integrity data found (looked for "${intField}" field)`);
+  }
+
+  // Validate each trial has the minimum required fields from the schema.
+  // Missing fields get a warning but don't prevent analysis.
+  for (const trial of trials) {
+    const missing = [];
+    for (const [field, spec] of Object.entries(TRIAL_REPORT_FIELDS)) {
+      if (spec.required && trial[field] === undefined) {
+        missing.push(field);
+      }
+    }
+    if (missing.length > 0) {
+      warnings.push(`Trial ${trial.trialId || '?'}: missing fields: ${missing.join(', ')}`);
+    }
+  }
+
+  const { session, score } = findSessionData(raw);
+  if (session === null && trials.length > 0) {
+    warnings.push('No session-level integrity data — some signals unavailable (did the experiment call getSessionReport()?)');
+  }
+
+  return { participantId, trials, warnings, metadata: raw.metadata || {}, session, score };
+}
+
+// Locates session-level integrity data in one of three locations, in priority order:
+//   1. raw.metadata.integritySession / integrityScore — the card-games convention.
+//   2. Last trial's integritySession / integrityScore — jsPsych addDataToLastTrial (Option A).
+//   3. Any trial's integritySession — fallback (Option B).
+// Returns { session, score }, both null if not found.
+function findSessionData(raw) {
+  // 1. card-games metadata convention
+  if (raw.metadata?.integritySession) {
+    return { session: raw.metadata.integritySession, score: raw.metadata.integrityScore || null };
+  }
+  // 2. jsPsych addDataToLastTrial convention (Option A)
+  if (Array.isArray(raw.trials) && raw.trials.length > 0) {
+    const last = raw.trials[raw.trials.length - 1];
+    if (last?.integritySession) {
+      return { session: last.integritySession, score: last.integrityScore || null };
+    }
+  }
+  // 3. Any-trial fallback
+  if (Array.isArray(raw.trials)) {
+    const t = raw.trials.find(x => x?.integritySession);
+    if (t) return { session: t.integritySession, score: t.integrityScore || null };
+  }
+  return { session: null, score: null };
+}
+
+// Maps rule-gallery legacy field names to CyborgHunter schema names.
+// The CLI can then use a single set of field names downstream.
+const LEGACY_FIELD_MAP = {
+  mouseTrack: 'mouseEvents',
+};
+
+// Normalizes tabAwayEvents[*].start from session-relative performance.now()
+// (milliseconds since browser navigation) to trial-relative milliseconds
+// (milliseconds since the trial began), stored as `startRel_ms`.
+//
+// The rule-gallery data schema stores mouseTrack entries with a per-trial
+// relative `t` field (zero-based per trial), but tabAwayEvents are stored
+// with session-relative `start` values. Without normalization, renderers
+// using the same x-scale plot tab-aways hundreds of thousands of ms off-canvas.
+//
+// Algorithm: trial boundaries exist in wall-clock (response.timestamp is the
+// trial END wall-clock, responseTime_ms is trial duration). We infer a
+// participant-level `sessionOffset_ms` = (performance.now() value at session
+// start) by using the relationship:
+//     tab.start == sessionOffset + trialStart_wallclockRel + positionInTrial
+// where positionInTrial ∈ [0, responseTime_ms]. We estimate sessionOffset as
+// the median of (firstTab.start - trialStartRel) across trials, clipped to
+// the valid range implied by each (trial, firstTab) pair.
+function normalizeTabAwayTimestamps(trials, raw) {
+  // P3 fast path: if every trial carries a monitor-supplied trialStart_perfNow
+  // (same clock as tabAwayEvents[*].start), compute startRel_ms by direct
+  // subtraction. This skips the heuristic estimator entirely and is exact.
+  const everyTrialHasPerfNow = trials.length > 0 && trials.every(t =>
+    typeof (t.trialStart_perfNow ?? t.startTime) === 'number'
+  );
+  if (everyTrialHasPerfNow) {
+    for (const trial of trials) {
+      const tabs = trial.tabAwayEvents;
+      if (!Array.isArray(tabs) || tabs.length === 0) continue;
+      const trialStart = trial.trialStart_perfNow ?? trial.startTime;
+      trial.tabAwayEvents = tabs.map(ta => ({
+        ...ta,
+        startRel_ms: typeof ta.start === 'number' ? ta.start - trialStart : null
+      }));
+    }
+    return;
+  }
+
+  // Legacy estimator path — used when the detector didn't record a
+  // per-trial performance.now() anchor (e.g., rule-gallery pre-P3 data).
+  const sessStartIso = raw.metadata?.startTime;
+  if (!sessStartIso) return;
+  const sessStartMs = Date.parse(sessStartIso);
+  if (!Number.isFinite(sessStartMs)) return;
+
+  // Precompute wall-clock trial start (ms since session start) for each trial.
+  const trialStartRels = trials.map(t => {
+    if (!t.timestamp || t.responseTime_ms == null) return null;
+    const endMs = Date.parse(t.timestamp);
+    if (!Number.isFinite(endMs)) return null;
+    return (endMs - sessStartMs) - t.responseTime_ms;
+  });
+
+  // Collect offset candidates from each trial that has ≥1 tab-away.
+  // For trial i with first tab at T and trialStartRel S, responseTime R:
+  //     offset ∈ [T - (S + R), T - S]  (tab must lie within [S, S+R])
+  // Median of midpoints is a robust estimator.
+  const candidates = [];
+  for (let i = 0; i < trials.length; i++) {
+    const tabs = trials[i].tabAwayEvents;
+    if (!Array.isArray(tabs) || tabs.length === 0) continue;
+    const S = trialStartRels[i];
+    const R = trials[i].responseTime_ms;
+    if (S == null || R == null) continue;
+    const T = tabs[0].start;
+    if (typeof T !== 'number') continue;
+    // Midpoint of the valid offset interval for this trial's first tab.
+    candidates.push((T - S - R / 2));
+  }
+
+  if (candidates.length === 0) return;
+
+  candidates.sort((a, b) => a - b);
+  const sessionOffset = candidates[Math.floor(candidates.length / 2)];
+
+  // Apply normalization — add startRel_ms, keep original start.
+  for (let i = 0; i < trials.length; i++) {
+    const tabs = trials[i].tabAwayEvents;
+    if (!Array.isArray(tabs) || tabs.length === 0) continue;
+    const S = trialStartRels[i];
+    if (S == null) continue;
+    trials[i].tabAwayEvents = tabs.map(ta => ({
+      ...ta,
+      startRel_ms: (typeof ta.start === 'number')
+        ? ta.start - sessionOffset - S
+        : null
+    }));
+  }
+}
+
+function mapLegacyFields(trial) {
+  const mapped = { ...trial };
+  for (const [oldName, newName] of Object.entries(LEGACY_FIELD_MAP)) {
+    if (mapped[oldName] !== undefined && mapped[newName] === undefined) {
+      mapped[newName] = mapped[oldName];
+      delete mapped[oldName];
+    }
+  }
+  // Flag distinguishes "no tracking hardware" from "tracked, zero events"
+  mapped.mouseDataAvailable = Array.isArray(mapped.mouseEvents) && mapped.mouseEvents.length > 0;
+  return mapped;
+}
+
+// Finds files matching a glob pattern in the given directory.
+// Supports:
+//   - `*.json`         (default, broadened to also match `*.csv`)
+//   - `*.csv`          (CSV-only)
+//   - `*.{json,csv}`   (explicit brace expansion)
+//   - `gallery_*.json` (other simple wildcard patterns)
+//
+// The default `*.json` is broadened to JSON-or-CSV because jsPsych's `.csv()`
+// save is the most common shape we'll see in the wild; users on JSON pipelines
+// are unaffected.
+function findFiles(dir, pattern) {
+  const matchers = expandPatternToMatchers(pattern);
+  const files = readdirSync(dir).filter(f => matchers.some(m => m.test(f)));
+  return files.map(f => join(dir, f)).sort();
+}
+
+// Turns a single user-facing pattern into one or more anchored RegExp matchers.
+// Brace expansion is the only "fancy" feature supported; everything else is the
+// classic wildcard-to-regex conversion.
+function expandPatternToMatchers(pattern) {
+  // Default broadens to JSON + CSV.
+  if (pattern === '*.json') return [/\.json$/i, /\.csv$/i];
+  // Brace pattern: *.{json,csv} → expand to ['*.json', '*.csv'].
+  const brace = pattern.match(/^(.*)\{([^}]+)\}(.*)$/);
+  if (brace) {
+    const [, prefix, alts, suffix] = brace;
+    return alts.split(',').map(a => globToRegex(prefix + a.trim() + suffix));
+  }
+  return [globToRegex(pattern)];
+}
+
+function globToRegex(pat) {
+  // Convert glob pattern to anchored regex: * → .*, escape dots.
+  return new RegExp('^' + pat.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$');
+}
+
+// Parses jsPsych CSV output into a Shape-1 raw object that extractIntegrityData
+// already understands: `{ [pidField]: ..., trials: [...rows...] }`.
+//
+// jsPsych saves CSV via Papa Parse's `unparse()`. Nested objects/arrays in trial
+// data (e.g., the `integrity` field returned by the extension's on_finish, or
+// the `integritySession` and `integrityScore` blobs attached to the last trial
+// via addDataToLastTrial) get JSON-stringified into single cells. We reverse
+// that here: any cell whose string value starts with `{` or `[` is run through
+// JSON.parse, restoring the nested structure for downstream analyzers.
+//
+// Participant ID is hoisted from the first row to the top level so the Shape-1
+// branch in extractIntegrityData picks it up via raw[pidField].
+function parseCsvToRaw(text, config) {
+  const pidField = config.participantIdField || 'participantId';
+  // Papa Parse mis-handles a trailing newline on the final cell of the last
+  // row (treats it as an unterminated quoted field). POSIX convention is to
+  // end text files with a newline, so almost every CSV from the wild has one.
+  // Trim trailing whitespace defensively.
+  const result = Papa.parse(text.replace(/\s+$/, ''), {
+    header: true,
+    skipEmptyLines: true,
+    dynamicTyping: true,  // numbers and booleans parsed natively, strings stay strings
+  });
+  const rows = result.data || [];
+
+  // Walk every cell; if it looks like JSON, parse it. Leave non-JSON strings alone.
+  for (const row of rows) {
+    for (const [key, val] of Object.entries(row)) {
+      if (typeof val !== 'string') continue;
+      const trimmed = val.trim();
+      if (trimmed.length === 0) continue;
+      const first = trimmed[0];
+      if (first !== '{' && first !== '[') continue;
+      try {
+        row[key] = JSON.parse(trimmed);
+      } catch {
+        // Cell looked like JSON but didn't parse — leave the raw string.
+        // This is rare (e.g., a free-text response that happens to start with `{`)
+        // and downstream code can handle string values gracefully.
+      }
+    }
+  }
+
+  // Hoist participant ID from the first row to the top level so Shape-1 ingest
+  // finds it via raw[pidField]. Falls back to 'unknown' if the column isn't there.
+  const participantId = rows[0]?.[pidField] ?? 'unknown';
+
+  return {
+    [pidField]: participantId,
+    trials: rows,
+  };
+}

package/src/cli/init.js

@@ -0,0 +1,31 @@
+// src/cli/init.js
+// Generates a minimal starter config file in the current directory.
+// The user edits dataDir and filePattern to point at their data.
+
+import { writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export async function runInit() {
+  const configPath = join(process.cwd(), 'cyborg-hunter.config.json');
+
+  if (existsSync(configPath)) {
+    console.log(`Config already exists: ${configPath}`);
+    console.log('Delete it first if you want to regenerate.');
+    return;
+  }
+
+  // Minimal config — just the fields every project needs to set.
+  // filePattern defaults to JSON-or-CSV because jsPsych's `.csv()` save is
+  // the most common format we see in the wild (rule-gallery uses JSON; most
+  // jsPsych setups use CSV).
+  const config = {
+    dataDir: './data',
+    filePattern: '*.{json,csv}',
+    outputDir: './cyborg-hunter-report'
+  };
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  console.log(`Created ${configPath}`);
+  console.log('Edit dataDir and filePattern to match your data location.');
+  console.log('See docs/configuration.md for all available options.');
+}

package/src/cli/renderers/event-log.js

@@ -0,0 +1,66 @@
+// src/cli/renderers/event-log.js
+// Writes event-log.csv — chronological clipboard/paste events across all participants.
+// Each row is one event with participant, trial, type, timestamp, and text (if paste).
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+export async function renderEventLog(participants, config) {
+  // duration_ms column is populated for tab-aways (which have intrinsic
+  // duration); empty for instantaneous events (copy, paste, drop, synthetic).
+  const header = 'participantId,trialId,eventType,timestamp,duration_ms,text';
+  const rows = [];
+
+  for (const p of participants) {
+    for (const trial of p.trials) {
+      const trialId = trial.trialId || trial.ruleId || '?';
+
+      // Paste events
+      for (const e of (trial.pasteEvents || [])) {
+        rows.push(formatRow(p.participantId, trialId, 'paste', e.t, '', e.text));
+      }
+
+      // Copy events
+      for (const e of (trial.copyEvents || [])) {
+        rows.push(formatRow(p.participantId, trialId, 'copy', e.t, '', ''));
+      }
+
+      // Drop events
+      for (const e of (trial.dropEvents || [])) {
+        rows.push(formatRow(p.participantId, trialId, 'drop', e.t, '', e.text));
+      }
+
+      // Synthetic insertions (text appeared without keystrokes)
+      for (const e of (trial.syntheticInsertions || [])) {
+        rows.push(formatRow(p.participantId, trialId, 'synthetic', e.t, '', e.text));
+      }
+
+      // Tab-away events. timestamp uses the session-absolute `start` (same
+      // performance.now() clock the copy/paste `t` field uses), so all rows
+      // in this CSV share one chronological scale. The `text` column carries
+      // the tab-away type (windowBlur / visibilityChange / etc.) so analysts
+      // can filter by trigger.
+      for (const e of (trial.tabAwayEvents || [])) {
+        rows.push(formatRow(p.participantId, trialId, 'tabAway', e.start, e.duration_ms, e.type || ''));
+      }
+    }
+  }
+
+  // Sort chronologically within each participant
+  const csv = [header, ...rows].join('\n') + '\n';
+  const outPath = join(config.outputDir, 'event-log.csv');
+  writeFileSync(outPath, csv);
+  console.log(`  event-log.csv — ${rows.length} events`);
+}
+
+function formatRow(pid, trialId, type, timestamp, duration, text) {
+  return [pid, trialId, type, timestamp ?? '', duration ?? '', escapeCSV(text ?? '')].join(',');
+}
+
+function escapeCSV(val) {
+  const str = String(val);
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}

package/src/cli/renderers/extensions.js

@@ -0,0 +1,43 @@
+// src/cli/renderers/extensions.js
+// Writes extensions.csv — lists which AI extensions/tools were detected
+// for which participants. One row per participant × extension.
+// Also includes sidebar detection as a separate row.
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+export async function renderExtensions(participants, config) {
+  const header = 'participantId,detectionType,name,details';
+  const rows = [];
+
+  for (const p of participants) {
+    const pid = p.participantId;
+
+    // Extensions detected (from browser scan)
+    const extensions = p.session?.aiExtensionsFound || p.trials[0]?.extensionsDetected || [];
+    for (const ext of extensions) {
+      const name = typeof ext === 'string' ? ext : ext.name || 'unknown';
+      rows.push(`${pid},extension,${escapeCSV(name)},`);
+    }
+
+    // Sidebar detection
+    const hasSidebar = p.trials.some(t => (t.sidebarGapPx || 0) > 0);
+    if (hasSidebar) {
+      const maxGap = Math.max(...p.trials.map(t => t.sidebarGapPx || 0));
+      rows.push(`${pid},sidebar,browser_sidebar,${maxGap}px gap`);
+    }
+  }
+
+  const csv = [header, ...rows].join('\n') + '\n';
+  const outPath = join(config.outputDir, 'extensions.csv');
+  writeFileSync(outPath, csv);
+  console.log(`  extensions.csv — ${rows.length} detections`);
+}
+
+function escapeCSV(val) {
+  const str = String(val);
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}