six-degrees 0.2.1 → 0.3.0

package/lib/sector-focus.js

@@ -0,0 +1,163 @@
+// Your sector (Settings): up to three sectors you work in, and how hard to
+// lean toward them. Companies in them get +1 ("lean") or +2 ("strong") on
+// their score, so the people there rank higher. A pick is one of the twelve
+// broad industries (lib/companies.js INDUSTRIES), which a company matches by
+// its one industry or by any of the industry's sectors, or a narrower sector
+// from the directory (lib/sector-directory.js), which it matches by the
+// directory's words. The
+// model itself is in lib/scoring.js (companyScore); this file is the setting
+// around it: what a valid choice is, the fingerprint the stored scores are
+// stamped with, and the dry run the page shows before you save (which a save
+// also reports).
+//
+// Pure functions; tests/sector.test.mjs pins them down.
+
+import { readNetwork, scoreNetwork, SECTOR_BONUS } from './scoring.js';
+import { SECTOR_KEYS, DIRECTORY_VERSION, sectorMatcher, sectorGroup } from './sector-directory.js';
+import { TIER_ORDER } from './tiers.js';
+
+export const MAX_SECTORS = 3;
+export const STRENGTHS = Object.keys(SECTOR_BONUS);
+
+/** Nothing chosen: the model as it is for everyone else. */
+export const NO_FOCUS = Object.freeze({ sectors: Object.freeze([]), strength: 'lean' });
+
+/**
+ * A sector focus as sent by the page → a clean one, or an Error whose message
+ * can be shown as is. Sectors are broad industry keys (the ones the rest of
+ * the app infers) and the directory's keys, deduplicated and kept in one
+ * order (each industry, then its sectors), so the same choice always stores
+ * the same way. A choice saved before the directory, of industries only,
+ * reads exactly as it did.
+ */
+export function parseSectorFocus(value) {
+  if (value === null || value === undefined) return { sectors: [], strength: 'lean' };
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error('Your sector must be a choice of sectors and a strength.');
+  const raw = value.sectors ?? [];
+  if (!Array.isArray(raw)) throw new Error('Sectors must be a list.');
+  for (const s of raw) {
+    if (!SECTOR_KEYS.includes(s)) throw new Error(`There is no sector called '${String(s).slice(0, 40)}'.`);
+  }
+  const sectors = SECTOR_KEYS.filter((k) => raw.includes(k));
+  if (sectors.length > MAX_SECTORS) throw new Error(`Pick up to ${MAX_SECTORS} sectors.`);
+  const strength = value.strength ?? 'lean';
+  if (!STRENGTHS.includes(strength)) throw new Error('Strength is lean or strong.');
+  return { sectors, strength };
+}
+
+/** How Settings declares it (lib/settings.js). */
+export const SECTOR_FOCUS_SETTING = { default: NO_FOCUS, parse: parseSectorFocus };
+
+/**
+ * A short, stable string for a focus, stamped beside the stored scores
+ * (app_meta 'scoring_focus'). If the saved focus stops matching it (a
+ * restored or imported database, a save whose rescore never finished, an
+ * update that changed the directory's words), the scores are stale and are
+ * recomputed on the next load. Every pick matches by the directory's word
+ * lists (a broad industry includes its sectors), so the fingerprint carries
+ * the directory's version: "lean:health,dental@<version>". Stamps from before
+ * a broad industry included its sectors ("lean:media,tech") no longer match,
+ * so those scores are redone once. `version` is for tests.
+ */
+export function focusFingerprint(focus, { version = DIRECTORY_VERSION } = {}) {
+  let f;
+  try { f = parseSectorFocus(focus); } catch { return 'none'; }
+  if (!f.sectors.length) return 'none';
+  return `${f.strength}:${f.sectors.join(',')}@${version}`;
+}
+
+export const sameFocus = (a, b) => focusFingerprint(a) === focusFingerprint(b);
+
+const RANK = Object.fromEntries(TIER_ORDER.map((t, i) => [t, TIER_ORDER.length - i]));
+
+/**
+ * Who changes tier between two scorings of the same rows. People are counted
+ * once (by profile URL) at their closest degree, the row the map shows.
+ * `tierBefore(row)` / `tierAfter(row)` return a tier letter or nothing.
+ * @returns { people, up, down, examples: [{ name, degree, company, from, to }] }
+ *   people is how many people the rows are (a person can be several rows).
+ */
+export function tierMoves(rows, tierBefore, tierAfter, { examples = 5, companyOf } = {}) {
+  const people = new Map();
+  for (const r of rows) {
+    const key = r.profile_url || `id:${r.id}`;
+    const prev = people.get(key);
+    if (!prev || (r.degree || 9) < (prev.degree || 9)) people.set(key, r);
+  }
+  const moves = [];
+  for (const r of people.values()) {
+    const from = tierBefore(r);
+    const to = tierAfter(r);
+    if (!to || from === to) continue;
+    moves.push({ r, from: from || null, to, up: (RANK[to] || 0) > (RANK[from] || 0) });
+  }
+  // The most telling first: into the highest tier, then out of the highest.
+  // When people move both ways, both show.
+  const ups = moves.filter((m) => m.up).sort((a, b) => RANK[b.to] - RANK[a.to] || (a.r.degree || 9) - (b.r.degree || 9));
+  const downs = moves.filter((m) => !m.up).sort((a, b) => (RANK[b.from] || 0) - (RANK[a.from] || 0) || (a.r.degree || 9) - (b.r.degree || 9));
+  const nUp = Math.min(ups.length, examples - Math.min(downs.length, Math.floor(examples / 2)));
+  const nDown = Math.min(downs.length, examples - nUp);
+  const pick = [...ups.slice(0, nUp), ...downs.slice(0, nDown)];
+  return {
+    people: people.size,
+    up: ups.length,
+    down: downs.length,
+    examples: pick.map((m) => ({
+      name: m.r.name || 'Someone',
+      degree: m.r.degree || null,
+      company: companyOf?.(m.r) || null,
+      from: m.from,
+      to: m.to,
+    })),
+  };
+}
+
+/**
+ * What changing the sector focus from `from` to `to` does to these rows,
+ * worked out in memory: every headline read once (the slow part), then the
+ * network scored once per focus. Nothing is written. Settings shows it before
+ * you save, with `from` the focus saved now; the save reports it afterwards
+ * (lib/rpc.js rescoreAll's compareWith), so what the preview says and what
+ * the save says are the same count. `overrides` are your company scores, and
+ * `industryOf`, `sectorsOf` and `groupOf` the injected inference and sector
+ * directory, as rescoreAll passes them (lib/rpc.js readForScoring); `read` is
+ * readNetwork() of these rows, when they have been read already.
+ * @returns { scored, people, companies, companiesUp, companiesDown, companyExamples, up, down, examples }
+ *   scored counts rows and people counts people; companies are those whose
+ *   score moves, up/down the people whose tier does.
+ */
+export function previewSectorFocus(rows = [], {
+  overrides = new Map(), industryOf, sectorsOf = sectorMatcher(), groupOf = sectorGroup, from = NO_FOCUS, to = NO_FOCUS, examples = 5,
+  read = readNetwork(rows, { industryOf, sectorsOf, groupOf }),
+} = {}) {
+  const before = scoreNetwork(rows, { overrides, focus: from, read });
+  const after = scoreNetwork(rows, { overrides, focus: to, read });
+
+  // Companies whose score moves, biggest first (by your people there now).
+  // Every company anyone names counts, a former employer too: its score moves
+  // like any other, and it can be the role that moves the person who named it.
+  // `sector` is the pick that leans the company (in either focus), else its industry.
+  const changed = [];
+  for (const [name, a] of before.companyScores) {
+    const b = after.companyScores.get(name);
+    if (!name || !b || a.score === b.score) continue;
+    const sector = b.sector || a.sector || read.companies.get(name)?.industry;
+    changed.push({ name, from: a.score, to: b.score, sector, people: read.headcount.get(name) || 0 });
+  }
+  changed.sort((x, y) => y.people - x.people || x.name.localeCompare(y.name));
+
+  const moved = tierMoves(rows,
+    (r) => before.scores.get(r.id)?.tier,
+    (r) => after.scores.get(r.id)?.tier,
+    { examples, companyOf: (r) => after.scores.get(r.id)?.company });
+
+  // `people` comes with the tier moves: people once each, as they are counted.
+  return {
+    scored: rows.length,
+    companies: changed.length,
+    companiesUp: changed.filter((c) => c.to > c.from).length,
+    companiesDown: changed.filter((c) => c.to < c.from).length,
+    companyExamples: changed.slice(0, examples).map(({ name, from: a, to: b, sector }) => ({ name, from: a, to: b, sector })),
+    ...moved,
+  };
+}

package/lib/sector-labels.js

@@ -0,0 +1,81 @@
+// Each pick's label, colour, industry and kind, for pages that only name a
+// pick (the profile's "Your Sectors"). The sector directory
+// (lib/sector-directory.js) holds the same labels beside its word lists, which
+// make it about 100 KB; a page that names a pick loads this instead.
+// tests/sector-directory.test.mjs checks that the two agree.
+
+import { INDUSTRIES, UNKNOWN_INDUSTRY } from './companies.js';
+
+// The directory's sectors: key → [label, the industry it sits under, kind].
+const SECTORS = {
+  software: ['Software & SaaS', 'tech', 'function'],
+  'ai-data': ['AI & Data', 'tech', 'function'],
+  cybersecurity: ['Cybersecurity', 'tech', 'function'],
+  telecom: ['Telecom', 'tech', 'industry'],
+  fintech: ['Fintech & Payments', 'finance', 'industry'],
+  banking: ['Banking & Lending', 'finance', 'industry'],
+  'vc-pe': ['Venture Capital & Private Equity', 'finance', 'industry'],
+  wealth: ['Wealth & Asset Management', 'finance', 'industry'],
+  insurance: ['Insurance', 'finance', 'industry'],
+  accounting: ['Accounting & Tax', 'finance', 'function'],
+  crypto: ['Crypto & Web3', 'finance', 'industry'],
+  hospitals: ['Hospitals & Clinics', 'health', 'industry'],
+  dental: ['Dental', 'health', 'industry'],
+  'pharma-biotech': ['Pharma & Biotech', 'health', 'industry'],
+  'medical-devices': ['Medical Devices', 'health', 'industry'],
+  'mental-health': ['Mental Health', 'health', 'industry'],
+  'fitness-wellness': ['Fitness & Wellness', 'health', 'industry'],
+  veterinary: ['Veterinary & Animal Care', 'health', 'industry'],
+  k12: ['K-12 Education', 'education', 'industry'],
+  'higher-ed': ['Higher Education', 'education', 'industry'],
+  'marketing-advertising': ['Marketing & Advertising', 'media', 'function'],
+  'pr-comms': ['PR & Communications', 'media', 'function'],
+  'media-publishing': ['Media & Publishing', 'media', 'industry'],
+  'creator-economy': ['Creator Economy', 'media', 'industry'],
+  'film-tv-music': ['Film, TV & Music', 'entertainment', 'industry'],
+  'gaming-esports': ['Gaming & Esports', 'entertainment', 'industry'],
+  sports: ['Sports', 'entertainment', 'industry'],
+  'ecommerce-retail': ['E-commerce & Retail', 'consumer', 'industry'],
+  'consumer-goods': ['Consumer Goods', 'consumer', 'industry'],
+  restaurants: ['Restaurants & Food Service', 'consumer', 'industry'],
+  'hospitality-travel': ['Hospitality & Travel', 'consumer', 'industry'],
+  'beauty-personal-care': ['Beauty & Personal Care', 'consumer', 'industry'],
+  logistics: ['Logistics & Supply Chain', 'industry', 'industry'],
+  manufacturing: ['Manufacturing', 'industry', 'industry'],
+  energy: ['Energy & Utilities', 'industry', 'industry'],
+  automotive: ['Automotive', 'industry', 'industry'],
+  agriculture: ['Agriculture & Farming', 'industry', 'industry'],
+  'aerospace-defense': ['Aerospace & Defense', 'defense', 'industry'],
+  military: ['Military', 'defense', 'industry'],
+  government: ['Government & Public Sector', 'defense', 'industry'],
+  legal: ['Legal', 'consulting', 'function'],
+  'management-consulting': ['Management Consulting', 'consulting', 'function'],
+  'hr-recruiting': ['HR & Recruiting', 'consulting', 'function'],
+  'security-services': ['Security Services', 'consulting', 'function'],
+  'real-estate': ['Real Estate', 'realestate', 'industry'],
+  'construction-trades': ['Construction & Trades', 'realestate', 'industry'],
+  charities: ['Nonprofits & Charities', 'nonprofit', 'industry'],
+  'social-work': ['Social Work & Human Services', 'nonprofit', 'industry'],
+  faith: ['Faith & Ministry', 'nonprofit', 'industry'],
+};
+
+const COLOR = new Map(INDUSTRIES.map((g) => [g.key, g.color]));
+
+const BY_KEY = new Map([
+  ...INDUSTRIES.map((g) => [g.key, Object.freeze({ key: g.key, label: g.label, color: g.color, group: g.key, kind: 'industry' })]),
+  ...Object.entries(SECTORS).map(([key, [label, group, kind]]) => [key, Object.freeze({
+    key, label, color: COLOR.get(group) || UNKNOWN_INDUSTRY.color, group, kind,
+  })]),
+]);
+
+/**
+ * A pick's label and colour, for a broad industry or a directory sector, with
+ * the industry it sits under and its kind: 'function' for a directory sector
+ * of work every company has (HR & Recruiting, Legal…), else 'industry'.
+ */
+export function sectorByKey(key) {
+  return BY_KEY.get(key) || { key, label: UNKNOWN_INDUSTRY.label, color: UNKNOWN_INDUSTRY.color, group: null, kind: null };
+}
+
+/** A pick's label, or nothing for a key that isn't one. */
+export const sectorLabel = (key) => BY_KEY.get(key)?.label;

package/lib/settings-effects.js

@@ -0,0 +1,59 @@
+// What saving a setting sets in motion. lib/settings.js only stores; the work a
+// change causes lives here, so the store needs none of the modules that work
+// uses (rescoring reads the settings itself, which would otherwise go in a
+// circle). A setting with no entry here is simply saved.
+
+import { rescoreAll } from './rpc.js';
+import { sameFocus, NO_FOCUS } from './sector-focus.js';
+
+// Each entry: `changed(before, after)` says whether a change matters (by
+// default, any change to the stored value), and `run(db, after, before)` does
+// the work and returns what to tell the page.
+const EFFECTS = {
+  sectorFocus: {
+    // Only a change to what scoring uses: a strength with no sectors picked
+    // scores exactly like nothing picked, so it saves without a rescore.
+    changed: (before, after) => !sameFocus(before, after),
+    // Scores depend on the sector focus, so everyone is rescored, as when a
+    // company score changes (app/api/company-scores). The answer says how many
+    // people changed tier, counted by the preview's own function from the same
+    // rows (rescoreAll's compareWith), so it says what the preview said.
+    run(db, after, before) {
+      try {
+        const { scored, people, up, down } = rescoreAll({ compareWith: before ?? NO_FOCUS });
+        return { scored, people, moved: up + down, up, down };
+      } catch (err) {
+        // The choice is saved and the old scores are stamped with the old
+        // choice, so the next load of the map sees they are stale and retries.
+        throw new Error(`Saved, but rescoring your network failed (${err.message}). It will try again the next time the map loads.`);
+      }
+    },
+  },
+};
+
+const differs = (before, after) => JSON.stringify(before) !== JSON.stringify(after);
+
+/**
+ * Run what each changed setting sets in motion. `before` and `after` are full
+ * settings objects as lib/settings.js returns them; `effects` defaults to the
+ * app's own (tests pass their own, as with lib/settings.js's schema).
+ * Every changed setting's work runs, even after another's fails.
+ * @returns { [setting]: its result } for those that ran, or null when none did.
+ * @throws an Error whose message names every failure, with `.effects` holding
+ *   the results of those that did run (or null).
+ */
+export function afterSettingsChange(db, before, after, effects = EFFECTS) {
+  let out = null;
+  const failed = [];
+  for (const [name, { changed = differs, run }] of Object.entries(effects)) {
+    if (!changed(before?.[name], after?.[name])) continue;
+    try {
+      const result = run(db, after?.[name], before?.[name]);
+      out = { ...out, [name]: result };
+    } catch (err) {
+      failed.push(err.message);
+    }
+  }
+  if (failed.length) throw Object.assign(new Error(failed.join(' ')), { effects: out });
+  return out;
+}

package/lib/settings.js

@@ -0,0 +1,83 @@
+// What the user chose on the Settings page.
+//
+// Kept in the database, not the browser: the browser's storage belongs to one
+// window's address and port (and in the Mac app lives outside the data
+// folder), so it would not travel with an export, a backup or a new computer.
+// Everything sits in one JSON object under app_meta 'settings'.
+//
+// Each setting a feature adds declares itself in SETTINGS below: its default,
+// and a parse() that returns the cleaned value or throws a plain-English
+// error. A key that isn't declared is refused, so a stale page or a stray
+// request can't plant values nothing reads.
+
+import { SECTOR_FOCUS_SETTING } from './sector-focus.js';
+
+export const SETTINGS = {
+  // Settings → Your sector: industries whose companies count for more (lib/sector-focus.js).
+  sectorFocus: SECTOR_FOCUS_SETTING,
+};
+
+const KEY = 'settings';
+
+/** A setting the user sent that can't be accepted; its message is shown as is. */
+export class SettingsError extends Error {}
+
+/** The stored object exactly as saved, keys this version doesn't know included. */
+function readStored(db) {
+  const row = db.prepare('SELECT value FROM app_meta WHERE key = ?').get(KEY);
+  if (!row?.value) return {};
+  try {
+    const parsed = JSON.parse(row.value);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch {
+    // A damaged value reads as "nothing chosen" rather than breaking every
+    // page. The next save overwrites it.
+  }
+  return {};
+}
+
+/** The stored settings, with defaults for anything never set. */
+export function readSettings(db, schema = SETTINGS) {
+  const stored = readStored(db);
+  const out = {};
+  for (const [name, def] of Object.entries(schema)) {
+    let value = def.default;
+    if (Object.hasOwn(stored, name)) {
+      try { value = def.parse(stored[name]); } catch { value = def.default; }
+    }
+    out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * Apply a partial change, validated, and store it.
+ *
+ * Only the settings in the patch are written. Everything else stays exactly as
+ * it was stored, including settings this version doesn't know and values it
+ * can't read: a newer copy (a beta, or an update on another Mac that shares the
+ * data) may have saved them, and an older copy saving its own choice must not
+ * erase them.
+ *
+ * @returns the full settings after the change.
+ * @throws SettingsError with a message fit to show the user; nothing is written.
+ */
+export function writeSettings(db, patch, schema = SETTINGS) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    throw new SettingsError('Settings must be an object.');
+  }
+  const changes = {};
+  for (const [name, value] of Object.entries(patch)) {
+    // Own keys only: 'constructor' or 'toString' aren't settings.
+    const def = Object.hasOwn(schema, name) ? schema[name] : null;
+    if (!def) throw new SettingsError(`There is no setting called '${name}'.`);
+    try {
+      changes[name] = def.parse(value);
+    } catch (err) {
+      throw new SettingsError(err.message);
+    }
+  }
+  db.prepare(`INSERT INTO app_meta (key, value) VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(KEY, JSON.stringify({ ...readStored(db), ...changes }));
+  return readSettings(db, schema);
+}