cyborg-hunter 0.3.0 → 0.5.0

package/src/cli/analyzers/triage.js

@@ -32,33 +32,45 @@ export function rankTriage(summaries, edgeExits, config) {
   return triageList;
 }
 
-// Combines all signal categories into a single numeric score.
-// Hard signals add +100 to ensure they always rank above soft-only participants.
-// Session-level signals (sidebar events, AI extensions, keyboard shortcuts, layout
-// shifts, zoom changes) are surfaced from session metadata when available.
-function computeTriageScore(summary, edgeExitCount) {
-  // Prefer session-authoritative soft score; fall back to per-trial sum.
-  let score = summary.authoritativeSoftScore ?? summary.totalSoftScore;
-  if (summary.hardTriggered) score += 100;
-  score += edgeExitCount * 3;
-
-  // Session-level: +5 per AI extension detected (canonical name: aiExtensionsFound)
+// Decomposes the composite triage score into [label, contribution] pairs.
+// Used by both computeTriageScore (sums them) and the HTML renderer (displays them
+// with bars). Keeping the formula here means the score breakdown in the report can
+// never silently disagree with the ranked score it explains.
+//
+// IMPORTANT: this function is **strictly behavior-preserving** vs the previous
+// inline computeTriageScore. The defensive `|| 0` fallbacks below match the
+// original exactly — no extra ones added, no original ones removed. Adding
+// new defenses changes how malformed data (e.g. a non-numeric softScore object)
+// is rendered into csv/md/png outputs, even when the well-formed-data score
+// would be the same. We promised existing users no surprises in this refactor.
+export function decomposeScore(summary, edgeExitCount, hardTriggered) {
   const aiExtensions = summary.aiExtensionsFound || summary.extensionsDetected || [];
-  score += aiExtensions.length * 5;
-
-  // Session-level: +3 per sidebar event, capped at 15 (≈ 5 events max contribution)
   const sidebarCount = summary.sidebarEventCount ?? (summary.sidebarDetected ? 1 : 0);
-  score += Math.min(sidebarCount * 3, 15);
-
-  // Session-level: +2 per DevTools-ish keyboard shortcut
-  score += (summary.keyboardShortcutCount || 0) * 2;
-
-  // Session-level: +1 per layout shift / zoom change (workspace perturbations)
-  score += (summary.layoutShiftCount || 0);
-  score += (summary.zoomChangeCount || 0);
+  const base         = summary.authoritativeSoftScore ?? summary.totalSoftScore;
+  return [
+    ['soft',     base],
+    ['hard',     hardTriggered ? 100 : 0],
+    ['edge',     edgeExitCount * 3],
+    ['ext',      aiExtensions.length * 5],
+    ['sidebar',  Math.min(sidebarCount * 3, 15)],
+    ['kb',       (summary.keyboardShortcutCount || 0) * 2],
+    ['layout',   (summary.layoutShiftCount || 0)],
+    ['zoom',     (summary.zoomChangeCount || 0)],
+    ['synth',    summary.totalSyntheticInsertions * 4],
+    ['foreign',  summary.totalForeignInputEvents * 3],
+  ];
+}
 
-  score += summary.totalSyntheticInsertions * 4;
-  score += summary.totalForeignInputEvents * 3;
+// computeTriageScore stays an internal helper. It accumulates the decomposition
+// in the original iteration order, starting from the soft base directly (NOT
+// from a defensive 0) — same `let score = base; score += hardTerm; score +=
+// edgeTerm; …` behaviour as the pre-refactor inline version. For malformed data
+// where `base` is a non-number (e.g. an object), every subsequent `+=` becomes
+// a string concat — exactly as it did before this refactor.
+function computeTriageScore(summary, edgeExitCount) {
+  const terms = decomposeScore(summary, edgeExitCount, summary.hardTriggered);
+  let score = terms[0][1];
+  for (let i = 1; i < terms.length; i++) score += terms[i][1];
   return score;
 }
 

package/src/cli/config.js

@@ -23,7 +23,7 @@ export function loadConfig(cliArgs) {
       fileConfig = JSON.parse(readFileSync(configPath, 'utf8'));
       console.log(`Loaded config from ${configPath}`);
     } catch (e) {
-      console.warn(`Warning: Failed to parse ${configPath}: ${e.message}`);
+      console.warn(`[cyborg-hunter] failed to parse ${configPath}: ${e.message}`);
     }
   }
 
@@ -43,7 +43,7 @@ export function loadConfig(cliArgs) {
 
   // Validate config file keys — warns about typos
   const warnings = validateConfig(fileConfig);
-  warnings.forEach(w => console.warn(`Warning: ${w}`));
+  warnings.forEach(w => console.warn(`[cyborg-hunter] ${w}`));
 
   return config;
 }

package/src/cli/ingest.js

@@ -1,17 +1,14 @@
-// src/cli/ingest.js
-// Loads JSON or CSV data files, extracts integrity data, validates schema.
+// Loads JSON or CSV participant 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: [...] }] }
+// Three input shapes:
+//   1. JSON Shape 1 — { participantId: 'P1', trials: [{ integrity: {...} }] }
+//      jsPsych extension data with one file per participant.
+//   2. JSON Shape 2 — { metadata: {...}, responses: [{ mouseTrack, tabAwayEvents, ... }] }
+//      The original rule-gallery format. Signal data lives flat on each response
+//      (no `integrity` wrapper). Pre-dates the standalone library.
 //   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).
+//      single cells. We unwrap them and route through Shape 1.
 
 import { readFileSync, readdirSync } from 'fs';
 import { join, extname } from 'path';
@@ -64,16 +61,16 @@ export function extractIntegrityData(raw, config) {
 
   let trials = [];
 
-  // Shape 1: { trials: [{ integrity: {...} }, ...] }
-  // Each trial has an `integrity` sub-object added by CyborgHunter's endTrial()
+  // Shape 1: { trials: [{ integrity: {...} }, ...] } — jsPsych extension data.
+  // Each trial has an `integrity` sub-object added by CyborgHunter.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.
+    // jsPsych extension data carries trialStart_perfNow per trial (set by the
+    // wrapper's on_load), so normalization takes the exact-subtraction fast
+    // path. Without it, renderers see only session-absolute `start` values
+    // and plot tab-away markers far off the per-trial axis.
     normalizeTabAwayTimestamps(trials, raw);
   }
   // Shape 2: { responses: [{ mouseTrack, tabAwayEvents, ... }] } (rule-gallery legacy format)
@@ -152,30 +149,27 @@ const LEGACY_FIELD_MAP = {
 };
 
 // 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.
+// (ms since browser navigation) to trial-relative ms (ms since this trial
+// began), stored as a new `startRel_ms` field. Renderers plot per-trial
+// against trial-relative time; without normalization, tab-away markers
+// land tens of thousands of ms off the right edge — invisible.
 //
-// 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.
+// Two paths:
+//   FAST PATH — every trial has a per-trial performance.now() anchor (either
+//     trialStart_perfNow set by the jsPsych wrapper, or startTime set by the
+//     standalone monitor). Subtract directly; result is exact.
+//   ESTIMATOR PATH — rule-gallery / pre-monitor data has neither anchor.
+//     We infer the session-start performance.now() value from the
+//     relationship between trial-end wall-clocks (`timestamp`),
+//     `responseTime_ms`, and the first tab-away's session-relative `start`,
+//     then subtract the inferred offset to get a trial-relative value.
+//     Less precise than the fast path; used only when nothing better exists.
 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 =>
+  // Fast path — every trial has a usable anchor.
+  const everyTrialHasAnchor = trials.length > 0 && trials.every(t =>
     typeof (t.trialStart_perfNow ?? t.startTime) === 'number'
   );
-  if (everyTrialHasPerfNow) {
+  if (everyTrialHasAnchor) {
     for (const trial of trials) {
       const tabs = trial.tabAwayEvents;
       if (!Array.isArray(tabs) || tabs.length === 0) continue;
@@ -188,14 +182,15 @@ function normalizeTabAwayTimestamps(trials, raw) {
     return;
   }
 
-  // Legacy estimator path — used when the detector didn't record a
-  // per-trial performance.now() anchor (e.g., rule-gallery pre-P3 data).
+  // Estimator path. Need a session-start wall-clock anchor; if there isn't
+  // one, we have no way to relate trial-end timestamps to a 0 reference.
   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.
+  // For each trial, compute trial-start in ms-since-session-start (wall-clock).
+  // trial-end is response.timestamp; trial-start = trial-end − duration.
   const trialStartRels = trials.map(t => {
     if (!t.timestamp || t.responseTime_ms == null) return null;
     const endMs = Date.parse(t.timestamp);
@@ -203,21 +198,26 @@ function normalizeTabAwayTimestamps(trials, raw) {
     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.
+  // For each trial that has ≥1 tab-away, estimate the session offset:
+  //   sessionOffset = (performance.now value at session start, in ms)
+  // The first tab-away of the trial must fall inside the trial's response
+  // window, so:
+  //   firstTabStart ∈ [sessionOffset + trialStartRel,
+  //                    sessionOffset + trialStartRel + trialDuration]
+  // Solving for sessionOffset gives an interval; we use the midpoint as
+  // each trial's candidate, then take the median across trials as the
+  // robust estimate. This is approximate but converges quickly with even
+  // a few tab-away-bearing trials.
   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));
+    const trialStartRel = trialStartRels[i];
+    const trialDurationMs = trials[i].responseTime_ms;
+    if (trialStartRel == null || trialDurationMs == null) continue;
+    const firstTabStart = tabs[0].start;
+    if (typeof firstTabStart !== 'number') continue;
+    candidates.push(firstTabStart - trialStartRel - trialDurationMs / 2);
   }
 
   if (candidates.length === 0) return;
@@ -225,16 +225,17 @@ function normalizeTabAwayTimestamps(trials, raw) {
   candidates.sort((a, b) => a - b);
   const sessionOffset = candidates[Math.floor(candidates.length / 2)];
 
-  // Apply normalization — add startRel_ms, keep original start.
+  // Apply normalization. Original `start` is preserved alongside `startRel_ms`
+  // so consumers can still see the absolute time if they want it.
   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;
+    const trialStartRel = trialStartRels[i];
+    if (trialStartRel == null) continue;
     trials[i].tabAwayEvents = tabs.map(ta => ({
       ...ta,
-      startRel_ms: (typeof ta.start === 'number')
-        ? ta.start - sessionOffset - S
+      startRel_ms: typeof ta.start === 'number'
+        ? ta.start - sessionOffset - trialStartRel
         : null
     }));
   }