cyborg-hunter 0.7.5 → 0.9.0

package/src/cli/analyzers/score-weights.js

@@ -0,0 +1,145 @@
+// src/cli/analyzers/score-weights.js
+// The report score's signal table and its weights (config.scoreWeights).
+//
+// The report score orders participants WITHIN a tier (see triage.js). Each
+// signal below contributes min(count, max) × weight. The default weights
+// reproduce the fixed 0.8.0 score: 5×paste + 5×copy + 3×sidebar + 1×tab-away
+// (tab-aways longer than the participant's threshold). Every other signal
+// defaults to 0 and can be switched on from cyborg-hunter.config.json:
+//
+//   "scoreWeights": { "synthetic": 1, "copy": { "weight": 5, "max": 3 } }
+//
+// A user's scoreWeights is merged PER KEY onto the defaults (the config loader
+// merges top-level keys only), so writing one key never zeroes the others.
+// The hard/soft/clean tier does not depend on these weights.
+
+import { findClosestKey } from '../../shared/validation.js';
+
+// Order matters: the first four are the 0.8.0 terms in their 0.8.0 order, so
+// default output (breakdown, totals) is unchanged. Counts copy the 0.8.0
+// expressions, including the sidebar fallback for pre-count data.
+export const SCORE_SIGNALS = [
+  { key: 'paste',          weight: 5, count: s => s.totalPasteEvents || 0 },
+  { key: 'copy',           weight: 5, count: s => s.totalCopyEvents || 0 },
+  { key: 'sidebar',        weight: 3, count: s => s.sidebarEventCount ?? (s.sidebarDetected ? 1 : 0) },
+  { key: 'tabaway',        weight: 1, count: s => (s.tabAwayLongCount || 0) + (s.tabAwayMediumCount || 0) },
+  { key: 'tabawayLong',    weight: 0, count: s => s.tabAwayLongCount || 0 },
+  { key: 'tabawayMedium',  weight: 0, count: s => s.tabAwayMediumCount || 0 },
+  { key: 'flicker',        weight: 0, count: s => s.tabAwayFlickerCount || 0 },
+  { key: 'drop',           weight: 0, count: s => s.totalDropEvents || 0 },
+  { key: 'fastTyping',     weight: 0, count: s => s.trialsWithFastTyping || 0 },
+  { key: 'synthetic',      weight: 0, count: s => s.totalSyntheticInsertions || 0 },
+  { key: 'foreignInput',   weight: 0, count: s => s.totalForeignInputEvents || 0 },
+  { key: 'aiExtensions',   weight: 0, count: s => (s.aiExtensionsFound || s.extensionsDetected || []).length },
+  { key: 'kbShortcuts',    weight: 0, count: s => s.keyboardShortcutCount || 0 },
+  { key: 'viewportShifts', weight: 0, count: s => s.layoutShiftCount || 0 },
+  { key: 'zoom',           weight: 0, count: s => s.zoomChangeCount || 0 },
+  // Edge exits are computed per trial by edge-exit.js and summed on the
+  // triage row; they are not a summary field.
+  { key: 'edgeExits',      weight: 0, count: (s, edgeExitCount) => edgeExitCount || 0 },
+];
+
+const KEYS = SCORE_SIGNALS.map(s => s.key);
+
+export const DEFAULT_SCORE_WEIGHTS = Object.fromEntries(SCORE_SIGNALS.map(s => [s.key, s.weight]));
+
+const show = v => {
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (typeof v === 'number' || v == null || typeof v === 'boolean') return String(v);
+  try { return JSON.stringify(v); } catch (e) { return typeof v; }
+};
+const isPlainObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const validWeight = w => typeof w === 'number' && Number.isFinite(w) && w >= 0;
+const validMax = m => Number.isInteger(m) && m >= 0;
+
+// Returns { weights: { key: { weight, max|null } }, isDefault, warnings }.
+// Invalid entries warn and keep that key's default; nothing here throws.
+export function resolveScoreWeights(user) {
+  const weights = Object.fromEntries(SCORE_SIGNALS.map(s => [s.key, { weight: s.weight, max: null }]));
+  const warnings = [];
+
+  if (user != null && !isPlainObject(user)) {
+    warnings.push(`scoreWeights must be an object of signal weights (got ${show(user)}); using the default weights.`);
+  } else if (user != null) {
+    for (const [key, value] of Object.entries(user)) {
+      if (key.toLowerCase() === 'devtools') {
+        warnings.push('scoreWeights.devTools is ignored: the DevTools count is always 0. DevTools hotkeys are counted under "kbShortcuts".');
+        continue;
+      }
+      if (!KEYS.includes(key)) {
+        const guess = findClosestKey(key, KEYS);
+        warnings.push(`scoreWeights: unknown signal "${key}"${guess ? ` (did you mean "${guess}"?)` : ''}; it is ignored. Keys are case-sensitive.`);
+        continue;
+      }
+      const slot = weights[key];
+      const def = DEFAULT_SCORE_WEIGHTS[key];
+      const obj = isPlainObject(value) ? value : null;
+      const hasWeight = obj ? obj.weight !== undefined : true;
+      // `max: null` means "no cap" — the shape score-weights.json writes — so a
+      // copy of that file used as scoreWeights resolves without warnings.
+      const hasMax = !!obj && obj.max != null;
+      const w = obj ? obj.weight : value;
+
+      if (obj) {
+        const extra = Object.keys(obj).filter(k => k !== 'weight' && k !== 'max');
+        if (extra.length) warnings.push(`scoreWeights.${key}: unknown field${extra.length > 1 ? 's' : ''} ${extra.map(k => `"${k}"`).join(', ')} ignored; only "weight" and "max" are read.`);
+      }
+      if (obj && !hasWeight) {
+        if (hasMax) warnings.push(`scoreWeights.${key} has a max but no weight; the default weight ${def} applies.`);
+        else if (!('max' in obj)) warnings.push(`scoreWeights.${key}: the weight must be a finite number ≥ 0 (got ${show(obj)}); using the default ${def}.`);
+      } else if (!validWeight(w)) {
+        warnings.push(`scoreWeights.${key}: the weight must be a finite number ≥ 0 (got ${show(obj ? w : value)}); using the default ${def}.`);
+      } else {
+        slot.weight = w;
+      }
+
+      if (hasMax) {
+        if (validMax(obj.max)) slot.max = obj.max;
+        else warnings.push(`scoreWeights.${key}.max must be a whole number ≥ 0 (got ${show(obj.max)}); no cap is applied.`);
+      }
+    }
+  }
+
+  if (weights.tabaway.weight !== 0 && (weights.tabawayLong.weight !== 0 || weights.tabawayMedium.weight !== 0)) {
+    warnings.push('scoreWeights: "tabaway" already counts long + medium tab-aways, so weighting "tabawayLong" or "tabawayMedium" as well double counts them. Set "tabaway": 0 to use the split keys.');
+  }
+  if (KEYS.every(k => weights[k].weight === 0)) {
+    warnings.push('scoreWeights: every weight is 0, so every report score will be 0.');
+  }
+
+  const isDefault = KEYS.every(k => !differsFromDefault(weights, k));
+  return { weights, isDefault, warnings };
+}
+
+// A cap on a zero-weight signal changes nothing, so it does not make the
+// weights custom.
+function differsFromDefault(weights, k) {
+  const { weight, max } = weights[k];
+  return weight !== DEFAULT_SCORE_WEIGHTS[k] || (max != null && weight !== 0);
+}
+
+export const DEFAULT_RESOLVED_WEIGHTS = resolveScoreWeights(null).weights;
+
+// "5×copy + 3×sidebar + 1×synthetic (max 3)": the weighted signals, in table
+// order, for prose that states the formula (triage.md, the console summary).
+// Callers keep their own verbatim wording for the default weights.
+export function formulaText(weights, times = '×') {
+  return KEYS.filter(k => weights[k].weight !== 0)
+    .map(k => `${weights[k].weight}${times}${k}${weights[k].max != null ? ` (max ${weights[k].max})` : ''}`)
+    .join(' + ') || '0';
+}
+
+// "copy 5 max 3, synthetic 1": only the keys that differ from the defaults,
+// in table order. Empty string when nothing differs.
+export function customWeightsText(weights) {
+  return KEYS.filter(k => differsFromDefault(weights, k))
+    .map(k => `${k} ${weights[k].weight}${weights[k].max != null ? ` max ${weights[k].max}` : ''}`)
+    .join(', ');
+}
+
+// The one formatter for displayed scores. Integers (every score under integer
+// weights, i.e. all default output) pass through unchanged, type included;
+// fractional scores print to one decimal; non-numbers pass through.
+export function formatScore(n) {
+  return typeof n === 'number' && !Number.isInteger(n) ? n.toFixed(1) : n;
+}

package/src/cli/analyzers/triage.js

@@ -5,24 +5,36 @@
 //
 // Ranking has two parts (see rankTriage + decomposeScore below):
 //   - tier:  hard-triggered → soft-flagged → clean (primary sort key)
-//   - score: 5×paste + 5×copy + 3×sidebar-open + 1×tab-away (within a tier),
-//            where a "tab-away" is one longer than the participant's tab-away
-//            threshold (3s by default, 5s for the strict preset)
-// Other signals (AI extensions, keyboard shortcuts, layout/zoom, edge-exits,
-// synthetic insertions, foreign inputs, honeypot disclosure) are surfaced in the
-// reason and detail panes but do NOT contribute to the score.
+//   - score: by default 5×paste + 5×copy + 3×sidebar-open + 1×tab-away (within
+//            a tier), where a "tab-away" is one longer than the participant's
+//            tab-away threshold (3s by default, 5s for the strict preset).
+//            config.scoreWeights can reweight these and switch on any other
+//            signal (see score-weights.js); the tier never depends on it.
+// Signals with weight 0 (by default: AI extensions, keyboard shortcuts,
+// layout/zoom, edge-exits, synthetic insertions, foreign inputs) and honeypot
+// disclosure are surfaced in the reason and detail panes but do not contribute
+// to the score.
+
+import { SCORE_SIGNALS, DEFAULT_RESOLVED_WEIGHTS, resolveScoreWeights } from './score-weights.js';
 
 export function rankTriage(summaries, edgeExits, config) {
+  // Resolved once per run. Warnings are not printed here: config.js
+  // (cliConfigWarnings) is the single place they reach the console.
+  const { weights } = resolveScoreWeights(config?.scoreWeights);
   const triageList = summaries.map((s, i) => {
     const ee = edgeExits[i];
     const totalEdgeExits = ee.edgeExits.reduce((sum, t) => sum + t.edgeExitCount, 0);
 
-    const score = computeTriageScore(s, totalEdgeExits);
+    const terms = decomposeScore(s, totalEdgeExits, s.hardTriggered, weights);
+    const score = sumTerms(terms);
     const reason = generateTriageReason(s, totalEdgeExits);
 
     return {
       participantId: s.participantId,
       score,
+      // The applied [signal, contribution] pairs; renderers draw these so the
+      // breakdown always matches the score that was ranked on.
+      terms,
       reason,
       hardTriggered: s.hardTriggered,
       // Threshold precedence: an explicit analyst-side CLI override
@@ -40,8 +52,8 @@ export function rankTriage(summaries, edgeExits, config) {
   // Sort tier-first (hard, then soft, then clean), and by score descending
   // within a tier. A hard-triggered participant (paste/drop over its count
   // threshold) is categorically more actionable than a high soft-signal count,
-  // so they must lead the "start here" triage.md even though the four-term
-  // score (paste/copy/sidebar/tab-away) no longer includes a hard-trigger term.
+  // so they must lead the "start here" triage.md even though the score (by
+  // default paste/copy/sidebar/tab-away) includes no hard-trigger term.
   // This matches the HTML index's "Tier" sort (hard:0, soft:1, clean:2; score
   // desc within tier).
   const tierRank = (t) => (t.hardTriggered ? 0 : t.softFlagged ? 1 : 2);
@@ -54,47 +66,51 @@ export function rankTriage(summaries, edgeExits, config) {
 }
 
 // Decomposes the composite triage score into [label, contribution] pairs.
-// Used by both computeTriageScore (sums them) and the HTML renderer (displays them
+// Used by both rankTriage (sums them, and keeps them on the row as `terms`) 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.
 //
-// Scoring policy (fixed 2026-06-01): only four signals contribute to the
-// score —
+// Each signal in SCORE_SIGNALS (score-weights.js) contributes
+// min(count, max) × weight; signals whose weight is 0 are left out of the list
+// (a weighted signal with a count of 0 stays in, as `[key, 0]`). The DEFAULT
+// weights are the 2026-06-01 policy, so without config.scoreWeights the result
+// is the 0.8.0 four-term list:
 //   5 × paste events
 //   5 × copy events
 //   3 × sidebar events (open cycles)
 //   1 × tab-aways longer than the participant's tab-away threshold (3s default,
 //       5s strict) — excludes at-or-below-cutoff flickers, which are mostly noise
 //       from brief URL-bar focus / window edge clicks
-// Hard-trigger, AI extensions, layout shifts, zoom changes, keyboard shortcuts,
-// edge exits, synthetic insertions, and foreign inputs no longer affect the
-// *score*. They are NOT hidden from review: every event list still renders in
-// the per-participant detail panes, and hard-triggered participants are still
-// surfaced via the hard/soft/clean tier (which is independent of this score).
-// edgeExitCount and hardTriggered remain in the signature for the renderer's
-// call site but are unused under this policy.
-export function decomposeScore(summary, edgeExitCount, hardTriggered) {
-  const sidebarCount = summary.sidebarEventCount ?? (summary.sidebarDetected ? 1 : 0);
-  const tabAwayMeaningful =
-    (summary.tabAwayLongCount || 0) + (summary.tabAwayMediumCount || 0);
-  return [
-    ['paste',    (summary.totalPasteEvents || 0) * 5],
-    ['copy',     (summary.totalCopyEvents  || 0) * 5],
-    ['sidebar',  sidebarCount * 3],
-    ['tabaway',  tabAwayMeaningful],
-  ];
+// Every other signal (AI extensions, layout shifts, zoom, keyboard shortcuts,
+// edge exits, synthetic insertions, foreign inputs, …) defaults to 0 and can be
+// weighted through config.scoreWeights. Nothing here affects the hard/soft/clean
+// tier, and unweighted signals still render in the per-participant detail panes.
+// hardTriggered stays in the signature for the renderer's call site; it is unused.
+export function decomposeScore(summary, edgeExitCount, hardTriggered, weights = DEFAULT_RESOLVED_WEIGHTS) {
+  const terms = [];
+  for (const sig of SCORE_SIGNALS) {
+    const { weight, max } = weights[sig.key];
+    if (weight === 0) continue;
+    const count = sig.count(summary, edgeExitCount);
+    terms.push([sig.key, (max == null ? count : Math.min(count, max)) * weight]);
+  }
+  return terms;
 }
 
-// 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];
+// sumTerms stays an internal helper. It sums the decomposition in order,
+// starting from the first term rather than a defensive 0, as the pre-refactor
+// inline version did. With every weight set to 0 the list is empty and the
+// score is 0. (Since 0.9.0 every term is multiplied by its weight, so malformed
+// string counts are coerced to numbers rather than string-concatenated as they
+// could be for the unmultiplied 0.8.0 tab-away term.)
+function sumTerms(terms) {
+  let score = terms.length ? terms[0][1] : 0;
   for (let i = 1; i < terms.length; i++) score += terms[i][1];
+  // Deliberately unrounded: ordering uses the exact sum, so no configured
+  // contribution, however small, can be erased. Binary noise from fractional
+  // weights (0.1 × 3 = 0.30000000000000004) is removed only where scores are
+  // displayed, by formatScore (score-weights.js).
   return score;
 }
 
@@ -141,7 +157,7 @@ export function generateTriageReason(summary, edgeExitCount = 0) {
   if (summary.totalSyntheticInsertions > 0) parts.push(`${summary.totalSyntheticInsertions} synthetic insertions`);
   if (summary.totalForeignInputEvents > 0) parts.push(`${summary.totalForeignInputEvents} foreign inputs`);
   // Guard-honeypot self-disclosure — a strong corroborating signal, surfaced in
-  // the reason though it does not feed the four-term score.
+  // the reason though it does not feed the score (it has no scoreWeights key).
   if (summary.honeypotAiUse) parts.push('self-reported AI use (honeypot)');
   if (parts.length === 0) parts.push('clean');
   return parts.join('; ');

package/src/cli/config.js

@@ -10,6 +10,7 @@ import { readFileSync, existsSync } from 'fs';
 import { resolve, join } from 'path';
 import { DEFAULT_CLI_CONFIG } from '../shared/schema.js';
 import { validateConfig } from '../shared/validation.js';
+import { resolveScoreWeights } from './analyzers/score-weights.js';
 
 export function loadConfig(cliArgs) {
   // Parse CLI flags into a simple key-value object
@@ -67,6 +68,20 @@ export function cliConfigWarnings(config) {
       `soft-flagged. Set it to a number.`
     );
   }
+  // The browser library's scoring rules look like they belong here too, but
+  // the CLI reads only scoring.softScoreThreshold; the report score's weights
+  // live in scoreWeights. Say so rather than ignore them silently.
+  const scoring = config?.scoring;
+  if (scoring && typeof scoring === 'object' && (scoring.soft != null || scoring.hard != null)) {
+    warnings.push(
+      'scoring.soft / scoring.hard configure the browser library, not the report; ' +
+      'the CLI ignores them (only scoring.softScoreThreshold is read). To weight ' +
+      'signals in the report score, use "scoreWeights".'
+    );
+  }
+  // This is the single place scoreWeights warnings reach the console
+  // (rankTriage resolves the same weights silently).
+  warnings.push(...resolveScoreWeights(config?.scoreWeights).warnings);
   return warnings;
 }