kryptheon 0.1.20 → 0.1.22

package/README.md

@@ -161,6 +161,40 @@ wanted, and one new name of the same kind. A button that is gone with nothing
 in its place, or a rename next to other new buttons, fails as it always did.
 Checks you added with the toolbar are never redirected.
 
+## Dashboard
+
+```
+npx kryptheon
+```
+
+In a terminal, with no command, this opens a page on your own machine
+(`http://127.0.0.1:4789/`) for this project: what is broken, what needs a
+look, every run, recent changes, and switches for each check. `Run now`
+replays your recordings or reads your code from the page. It is only
+reachable from this machine; press Ctrl+C to stop it. From a script, use
+`npx kryptheon dashboard`.
+
+It opens on the one thing to do next, and under it "Start here": read your
+code, record your main flows, replay them, check your database - in that
+order, each marked done only once it has actually run.
+
+Checks that are not built yet are listed as "not available" - never as
+passed.
+
+## Reading your code
+
+```
+npx kryptheon code
+```
+
+Reads your frontend code for values put into the page as HTML - `innerHTML`,
+`insertAdjacentHTML`, `document.write`, React's `dangerouslySetInnerHTML`,
+Vue's `v-html`. If such a value can hold text someone typed, a `<` in it can
+run script with the signed-in person's session. Nothing is run; every result
+is "verification required", ranked HIGH when the value comes from a server
+response or an error message, MEDIUM when the code alone cannot say. The fix
+prompt for each one names the file, line and value.
+
 ## What goes where
 
 Only your recordings go in your project, in `tests/`. Everything Kryptheon

package/bin/kryptheon.js

@@ -85,6 +85,10 @@ function usage() {
   console.log('  npx kryptheon accept <name>  agree that one test\'s new result is the correct one');
   console.log('  npx kryptheon remove [name]  list the recordings, or remove one you no longer want');
   console.log('  npx kryptheon setup-ai       tell your AI assistant to check its work');
+  console.log('  npx kryptheon verify         after a change: what changed, what broke, what got fixed');
+  console.log('  npx kryptheon recheck [id]   prove a fix: run the check again, and say FIXED or not');
+  console.log('  npx kryptheon code           read your frontend code for text inserted as HTML');
+  console.log('  npx kryptheon dashboard      open this project\'s dashboard (also: npx kryptheon, in a terminal)');
   console.log('');
   console.log('  add --quiet to check for one line when everything passes');
   console.log('  npx kryptheon --version      print the version you have installed');
@@ -1984,6 +1988,377 @@ function setupAi() {
   return results.some((r) => r.action === 'failed') ? 1 : 0;
 }
 
+// --- code -------------------------------------------------------------------
+//
+// A read of the project's own frontend code for text inserted as HTML
+// (kryptheon-code.js). Nothing is run and nothing is sent; every finding is
+// "verification required", so the exit code is 0 unless the read could not
+// happen at all - a script must never take an unproven risk for a break.
+
+// How many fix prompts are printed in full. The rest are saved in the store
+// and shown by the dashboard; forty prompts in a terminal is a wall nobody reads.
+const CODE_PROMPTS_SHOWN = 5;
+
+// The read itself, saved to the store. Shared by the command and the
+// dashboard's "Run now", so both leave the same record behind.
+function readCodeAndSave(opened) {
+  const reader = require(path.join(PACKAGE_DIR, 'kryptheon-code.js'));
+  const result = reader.scanProject(USER_DIR, { packageDir: PACKAGE_DIR });
+  if (!result.ran) return result;
+  try {
+    fs.writeFileSync(opened.codeFindings, JSON.stringify({
+      checkedAt: new Date().toISOString(),
+      filesRead: result.filesRead,
+      findings: result.findings,
+      unreadable: result.unreadable,
+    }, null, 2) + String.fromCharCode(10), 'utf8');
+  } catch (err) {
+    result.saveError = err.message;
+  }
+  return result;
+}
+
+function codeRead() {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+
+  const result = readCodeAndSave(opened);
+  if (!result.ran) {
+    console.error('');
+    console.error('  I could not read your code this time: ' + result.why + '.');
+    console.error('  Nothing was checked - this is not a pass.');
+    console.error('');
+    return 2;
+  }
+  if (result.saveError) console.error('  (could not save this read: ' + result.saveError + ')');
+
+  const high = result.findings.filter((f) => f.severity === 'HIGH');
+  const medium = result.findings.filter((f) => f.severity !== 'HIGH');
+  console.log('');
+  console.log('  I read ' + result.filesRead + ' file' + (result.filesRead === 1 ? '' : 's') + ' of your app\'s code.');
+  if (!result.findings.length) {
+    console.log('  I found no place where text that could come from outside the page is');
+    console.log('  inserted as HTML. That is what this read looks for, and only that.');
+  } else {
+    console.log('  ' + result.findings.length + ' place' + (result.findings.length === 1 ? '' : 's') +
+      ' where text may be inserted as HTML (' + high.length + ' HIGH, ' + medium.length + ' MEDIUM).');
+    console.log('  I did not run anything, so each one needs a look before it is called a bug.');
+    for (const f of high.concat(medium)) {
+      console.log('');
+      console.log('  ' + f.severity + '   ' + f.file + ':' + f.line + '   (verification required)');
+      console.log('    ' + f.headline);
+      console.log('    ' + f.sink + ':  ' + f.expression);
+    }
+    const prompted = high.slice(0, CODE_PROMPTS_SHOWN);
+    if (prompted.length) {
+      console.log('');
+      console.log('  ' + '-'.repeat(68));
+      console.log('  For the HIGH ones, paste this into your AI tool - one at a time:');
+      for (const f of prompted) {
+        console.log('');
+        f.fixPrompt.split(String.fromCharCode(10)).forEach((l) => console.log('    ' + l));
+      }
+    }
+    if (result.findings.length > prompted.length) {
+      console.log('');
+      console.log('  The fix for every one is saved in:');
+      console.log('    ' + opened.codeFindings);
+    }
+  }
+  if (result.unreadable.length) {
+    console.log('');
+    console.log('  What I could not read (unknown, not clear):');
+    for (const u of result.unreadable) console.log('    ' + u.file + ' - ' + u.why);
+  }
+  console.log('');
+  return 0;
+}
+
+// --- verify -----------------------------------------------------------------
+//
+// The command for the end of an AI task: what changed since Kryptheon last
+// looked, which checks that calls for, run the ones that can run here, and
+// say what broke and what got fixed. "The AI said done" is not the answer;
+// this is. The looking itself is kryptheon-look.js, shared with the dashboard.
+
+function verify() {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+  const looker = require(path.join(PACKAGE_DIR, 'kryptheon-look.js'));
+
+  const result = looker.look(USER_DIR, {
+    beforeRun: (diff, now) => {
+      console.log('');
+      if (diff.first) {
+        console.log('  First look at this project: ' + Object.keys(now.files).length + ' files noted.');
+        console.log('  Next time, I will say exactly what changed since now.');
+      } else if (!diff.files.length) {
+        console.log('  Nothing changed since the last look.');
+      } else {
+        console.log('  WHAT CHANGED   ' + diff.files.length + ' file' + (diff.files.length === 1 ? '' : 's') + ', in: ' + diff.parts.join(', '));
+        for (const part of diff.parts) {
+          const inPart = diff.files.filter((f) => f.part === part);
+          console.log('');
+          console.log('    ' + part);
+          for (const f of inPart.slice(0, 15)) console.log('      ' + f.state.padEnd(9) + f.path);
+          if (inPart.length > 15) console.log('      ... and ' + (inPart.length - 15) + ' more');
+          if (part === 'dependencies') {
+            for (const d of diff.dependencies) {
+              console.log('      package ' + d.name + ': ' + (d.change === 'added' ? 'added ' + d.to : d.change === 'removed' ? 'removed (was ' + d.from + ')' : d.from + ' -> ' + d.to));
+            }
+          }
+        }
+      }
+    },
+    frontend: () => readCodeAndSave(opened),
+    regression: () => {
+      console.log('');
+      console.log('  Replaying your recordings...');
+      const r = spawnSync(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'check', '--quiet'], {
+        cwd: USER_DIR,
+        stdio: 'inherit',
+        env: process.env,
+      });
+      return r.status;
+    },
+  }, { by: 'verify' });
+
+  const { diff, plan, fresh, fixed, removed, openConfirmed, after } = result;
+  console.log('');
+  if (plan.length) {
+    console.log('  CHECKS');
+    for (const step of plan) console.log('    ' + step.id.padEnd(12) + step.state);
+  } else if (!diff.first && diff.files.length) {
+    console.log('  CHECKS   none apply to this change (' + diff.parts.join(', ') + ').');
+  }
+
+  console.log('');
+  if (diff.first) {
+    console.log('  STARTING POINT   ' + after.findings.length + ' finding' + (after.findings.length === 1 ? '' : 's') +
+      ' already here (see npx kryptheon dashboard). Only what changes from now on will be called new.');
+  } else {
+    if (fresh.length) {
+      console.log('  WHAT BROKE   ' + fresh.length + ' new');
+      for (const f of fresh) {
+        console.log('    ' + f.severity + '   ' + f.status + '   ' + f.where);
+        console.log('      ' + f.headline);
+      }
+    } else {
+      console.log('  WHAT BROKE   nothing new that the checks above could see.');
+    }
+    if (fixed.length) {
+      console.log('');
+      console.log('  WHAT GOT FIXED   ' + fixed.length);
+      for (const f of fixed) console.log('    ' + f.where + '   ' + f.headline);
+    }
+    if (removed.length) {
+      console.log('');
+      console.log('  GONE WITH ITS FILE   ' + removed.length + ' (the file was deleted - not the same as fixed)');
+      for (const f of removed) console.log('    ' + f.where + '   ' + f.headline);
+    }
+  }
+  if (openConfirmed.length) {
+    console.log('');
+    console.log('  Still broken: ' + openConfirmed.length + ' confirmed problem' + (openConfirmed.length === 1 ? '' : 's') + '. The fix prompts are in the dashboard.');
+  }
+  console.log('');
+  if (result.saveError) console.error('  (could not save this look: ' + result.saveError + ')');
+
+  // Non-zero while anything confirmed is broken - new or not - so an AI tool
+  // reading only the exit code is never told its work left things fine when
+  // they are not. Findings that only need a look do not count.
+  return openConfirmed.length || result.regressionExit === 1 ? 1 : 0;
+}
+
+// --- recheck ----------------------------------------------------------------
+//
+// The end of the fix loop: prove a fix. The finding's own check runs again,
+// and so does everything the changes since call for, so "fixed" never means
+// "the code changed", and a fix that broke something else says so.
+
+function replayForLoop() {
+  console.log('');
+  console.log('  Replaying your recordings...');
+  const r = spawnSync(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'check', '--quiet'], {
+    cwd: USER_DIR,
+    stdio: 'inherit',
+    env: process.env,
+  });
+  return r.status;
+}
+
+const VERDICT_WORDS = {
+  fixed: 'FIXED',
+  'still open': 'STILL OPEN',
+  'gone with its file': 'GONE WITH ITS FILE (not the same as fixed)',
+  'could not confirm': 'COULD NOT CONFIRM',
+};
+
+function recheckCommand(id) {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+  const looker = require(path.join(PACKAGE_DIR, 'kryptheon-look.js'));
+  const dash = require(path.join(PACKAGE_DIR, 'kryptheon-dashboard.js'));
+
+  if (!id) {
+    const open = dash.buildState(USER_DIR).findings;
+    console.log('');
+    if (!open.length) {
+      console.log('  Nothing is open. There is nothing to re-check.');
+    } else {
+      console.log('  Open findings - re-check one after fixing it:  npx kryptheon recheck <id>');
+      console.log('');
+      for (const f of open) console.log('    ' + f.id + '   ' + f.severity.padEnd(8) + f.status.padEnd(23) + f.where + '   ' + f.headline);
+    }
+    console.log('');
+    return 0;
+  }
+
+  const r = looker.recheck(USER_DIR, { frontend: () => readCodeAndSave(opened), regression: replayForLoop }, String(id).trim());
+  console.log('');
+  if (!r.found) {
+    console.error('  There is no open finding with the id ' + id + '.');
+    console.error('  npx kryptheon recheck, on its own, lists the ones that are open.');
+    console.error('');
+    return 1;
+  }
+  console.log('  RE-CHECK   ' + r.id + '   ' + r.where);
+  console.log('    ' + r.headline);
+  console.log('');
+  console.log('  VERDICT    ' + VERDICT_WORDS[r.verdict] + (r.why ? ' - ' + r.why : ''));
+  if (r.newProblems.length) {
+    console.log('');
+    console.log('  NEW PROBLEMS   ' + r.newProblems.length + ' appeared with this change:');
+    for (const p of r.newProblems) console.log('    ' + p.id + '   ' + p.severity + '   ' + p.status + '   ' + p.where + '   ' + p.headline);
+  } else if (r.verdict === 'fixed') {
+    console.log('');
+    console.log('  Nothing new broke that the checks could see.');
+  }
+  console.log('');
+  if (r.verdict === 'could not confirm') return 2;
+  return r.verdict === 'fixed' && !r.newProblems.length ? 0 : 1;
+}
+
+// --- dashboard --------------------------------------------------------------
+//
+// One page on this machine for everything Kryptheon knows about this project
+// (kryptheon-dashboard.js). Runs until Ctrl+C.
+
+const DASHBOARD_PORT = 4789;
+
+function runFromDashboard(id, opened) {
+  if (id === 'frontend') {
+    const result = readCodeAndSave(opened);
+    return result.ran ? { ok: true } : { ok: false, why: result.why };
+  }
+  if (id === 'regression') {
+    // The same command a person types, as a separate process, so the page
+    // stays answerable while a browser replays the flows.
+    return new Promise((resolve) => {
+      const child = spawn(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'check', '--quiet'], {
+        cwd: USER_DIR,
+        stdio: 'ignore',
+        env: process.env,
+      });
+      child.on('error', (err) => resolve({ ok: false, why: err.message }));
+      // A run that found broken flows is a run that finished; its results are
+      // in the history the page reads next.
+      child.on('close', (code) => resolve(code === 0 || code === 1 ? { ok: true, exit: code } : { ok: false, why: 'the run stopped with exit ' + code }));
+    });
+  }
+  return { ok: false, why: '"' + id + '" cannot be run from the dashboard' };
+}
+
+async function dashboardCommand() {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+  const dash = require(path.join(PACKAGE_DIR, 'kryptheon-dashboard.js'));
+  const app = dash.createServer(USER_DIR, {
+    run: (id) => runFromDashboard(id, opened),
+    // The same `recheck` a person types, in its own process, so the page stays
+    // answerable while a flow is replayed. Its verdict is read from the store.
+    recheck: (id) => new Promise((resolve) => {
+      // Only a verdict written by this re-check counts: an older one for the
+      // same finding, read after a child that failed early, would be a stale
+      // answer shown as a fresh one.
+      const startedAt = new Date().toISOString();
+      const child = spawn(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'recheck', id], {
+        cwd: USER_DIR,
+        stdio: 'ignore',
+        env: process.env,
+      });
+      child.on('error', (err) => resolve({ ok: false, why: err.message }));
+      child.on('close', () => {
+        let last = null;
+        try {
+          const lines = fs.readFileSync(opened.fixes, 'utf8').split(String.fromCharCode(10)).filter(Boolean);
+          for (let i = lines.length - 1; i >= 0 && !last; i--) {
+            const a = JSON.parse(lines[i]);
+            if (a.id === id && a.at >= startedAt) last = a;
+          }
+        } catch (err) {
+          last = null;
+        }
+        resolve(last || { ok: false, why: 'the re-check did not record a verdict' });
+      });
+    }),
+  });
+  let port;
+  try {
+    port = await app.listen(DASHBOARD_PORT);
+  } catch (err) {
+    // Taken - by another project's dashboard, most likely. Any free port will do.
+    port = await app.listen(0);
+  }
+  console.log('');
+  console.log('  Kryptheon dashboard for ' + path.basename(USER_DIR) + ':');
+  console.log('');
+  console.log('    http://127.0.0.1:' + port + '/');
+  console.log('');
+  console.log('  Open that address in your browser. It is only reachable from this');
+  console.log('  machine. Press Ctrl+C here to stop it.');
+  console.log('');
+
+  // While the page is open, Kryptheon notices changes by itself: once a change
+  // has settled, it looks, runs the fast checks, and the page shows what
+  // changed and what came of it. Recordings are replayed only from the page's
+  // Run now - a replay while the app is down would call every flow broken.
+  const looker = require(path.join(PACKAGE_DIR, 'kryptheon-look.js'));
+  looker.startWatch(USER_DIR, {
+    frontend: () => readCodeAndSave(opened),
+    regression: () => null,
+  }, {
+    onLook: (r) => {
+      if (r.diff.first) return;
+      const when = new Date().toLocaleTimeString();
+      console.log('  ' + when + '  ' + r.diff.files.length + ' file' + (r.diff.files.length === 1 ? '' : 's') + ' changed (' +
+        r.diff.parts.join(', ') + ') - ' + r.fresh.length + ' new, ' + r.fixed.length + ' fixed. See the page.');
+    },
+    onError: (err) => console.error('  (could not look at a change: ' + err.message + ')'),
+  });
+  return new Promise(() => {});
+}
+
 // --- accept -----------------------------------------------------------------
 
 function baselineApi() {
@@ -2243,12 +2618,27 @@ async function main() {
     case 'accept':
       return finishWith(accept(rest.join(' ').trim()));
       break;
+    case 'code':
+      return finishWith(codeRead());
+    case 'verify':
+      return finishWith(verify());
+    case 'recheck':
+      return finishWith(recheckCommand(rest[0]));
     case '-v':
     case '--version':
     case 'version':
       console.log(packageVersion());
       return finishWith(0);
+    case 'dashboard':
+      return finishWith(await dashboardCommand());
     case undefined:
+      // One command starts Kryptheon - in a terminal a person is looking at.
+      // Run by a script or an AI tool there is nobody to open a page for, and
+      // a server that never exits would hang it, so it prints the usage as it
+      // always did.
+      if (process.stdin.isTTY && process.stdout.isTTY) return finishWith(await dashboardCommand());
+      usage();
+      return finishWith(0);
     case '-h':
     case '--help':
     case 'help':

package/kryptheon-changes.js

@@ -0,0 +1,222 @@
+// What changed in a project since Kryptheon last looked, and what that means
+// for which checks have to run.
+//
+// A snapshot is a content hash of every file that is the project's own - its
+// source, its database migrations, its dependency list - kept in the store,
+// never in the project. Comparing two snapshots answers the first question a
+// person has after an AI tool says "done": what did it actually touch?
+//
+// Content, not timestamps and not git: an editor that saves a file unchanged
+// is not a change, and a landing page with no git repository still has one.
+//
+// Each changed file is put in a part of the app (frontend, backend, database,
+// tests, dependencies, config, docs), and each part names the checks that
+// can speak to it. The mapping is written here, once, and deliberately
+// plain: a path-based guess that is right for how most projects are laid
+// out, and said as a guess ("likely affected") rather than a proof.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', '.next', '.nuxt', '.svelte-kit', 'coverage',
+  '.vercel', '.netlify', '.turbo', '.cache', 'test-results', 'playwright-report', '.kryptheon',
+]);
+const MAX_BYTES = 5 * 1024 * 1024;
+
+// Where a file sits in the app. The first rule that matches wins, so the
+// specific ones come first: a .sql file inside backend/ is a database change.
+const PARTS = [
+  { part: 'dependencies', test: (p) => /(^|\/)(package\.json|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|requirements\.txt|poetry\.lock|Gemfile\.lock|go\.sum)$/i.test(p) },
+  { part: 'database', test: (p) => /\.sql$/i.test(p) || /(^|\/)(migrations|supabase|prisma|drizzle|db\/schema)(\/|$)/i.test(p) || /(^|\/)schema\.prisma$/i.test(p) },
+  { part: 'tests', test: (p) => /(^|\/)(tests?|__tests__|e2e|cypress)\//i.test(p) || /\.(spec|test)\.[cm]?[jt]sx?$/i.test(p) },
+  { part: 'docs', test: (p) => /\.(md|mdx|txt|rst)$/i.test(p) || /(^|\/)docs\//i.test(p) },
+  { part: 'config', test: (p) => /(^|\/)(\.env\.example|\.env\.sample|tsconfig[^/]*\.json|jsconfig\.json|vercel\.json|netlify\.toml|dockerfile|docker-compose[^/]*\.ya?ml)$/i.test(p) || /\.config\.[cm]?[jt]s$/i.test(p) || /(^|\/)\.github\//i.test(p) },
+  { part: 'backend', test: (p) => /(^|\/)(server|backend|api|routes|controllers|services|middleware|functions|workers|jobs|lib\/server)(\/|\.[cm]?[jt]s$)/i.test(p) || /(^|\/)(server|app|index)\.[cm]?[jt]s$/i.test(p) && !/(^|\/)(src|public|frontend|client|pages|components)\//i.test(p) },
+  { part: 'frontend', test: (p) => /\.(html?|css|scss|sass|less|jsx|tsx|vue|svelte|astro)$/i.test(p) || /(^|\/)(frontend|client|public|src|pages|components|app|views|static)\//i.test(p) && /\.[cm]?[jt]s$/i.test(p) },
+  { part: 'assets', test: (p) => /\.(png|jpe?g|gif|svg|webp|ico|woff2?|ttf|otf|mp4|webm|mp3|pdf)$/i.test(p) },
+];
+
+// Which checks can speak to a change in each part. Ids are the dashboard's.
+const CHECKS_FOR = {
+  frontend: ['frontend', 'regression'],
+  backend: ['backend', 'api', 'regression'],
+  database: ['data', 'regression'],
+  dependencies: ['dependency', 'build', 'regression'],
+  tests: ['regression'],
+  config: ['build', 'regression'],
+  code: ['regression'],
+  docs: [],
+  assets: [],
+};
+
+function partOf(rel) {
+  const p = rel.split(path.sep).join('/');
+  const hit = PARTS.find((r) => r.test(p));
+  if (hit) return hit.part;
+  return /\.[cm]?[jt]sx?$/i.test(p) ? 'code' : 'other';
+}
+
+/** Every file that is the project's own, as relative paths with forward slashes. */
+function listFiles(root) {
+  const out = [];
+  (function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) walk(full);
+      } else if (entry.isFile()) {
+        // A real .env holds secrets; its content is never hashed or kept.
+        if (/^\.env(\..+)?$/i.test(entry.name) && !/\.(example|sample)$/i.test(entry.name)) continue;
+        out.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  })(root);
+  return out.sort();
+}
+
+/** The dependency lists of package.json, kept so a change can say which package moved. */
+function dependenciesOf(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    return Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * The project as it is now. Files whose size and modified time match the
+ * previous snapshot keep its hash without being read again - on a large
+ * project that is the difference between milliseconds and seconds, and an
+ * unchanged size and time is the same bytes for every editor that exists.
+ */
+function takeSnapshot(root, previous) {
+  const before = (previous && previous.files) || {};
+  const files = {};
+  for (const rel of listFiles(root)) {
+    let stat;
+    try {
+      stat = fs.statSync(path.join(root, rel));
+    } catch (err) {
+      continue;
+    }
+    const old = before[rel];
+    if (old && old.size === stat.size && old.mtimeMs === stat.mtimeMs) {
+      files[rel] = old;
+      continue;
+    }
+    let hash;
+    if (stat.size > MAX_BYTES) {
+      hash = 'size:' + stat.size + ':' + stat.mtimeMs;
+    } else {
+      try {
+        hash = crypto.createHash('sha1').update(fs.readFileSync(path.join(root, rel))).digest('hex');
+      } catch (err) {
+        continue;
+      }
+    }
+    files[rel] = { hash: hash, size: stat.size, mtimeMs: stat.mtimeMs };
+  }
+  return { takenAt: new Date().toISOString(), files: files, dependencies: dependenciesOf(root) };
+}
+
+/** Packages added, removed or moved to another version between two snapshots. */
+function dependencyChanges(before, after) {
+  const a = (before && before.dependencies) || {};
+  const b = (after && after.dependencies) || {};
+  const out = [];
+  for (const name of new Set(Object.keys(a).concat(Object.keys(b)))) {
+    if (!(name in a)) out.push({ name: name, change: 'added', to: b[name] });
+    else if (!(name in b)) out.push({ name: name, change: 'removed', from: a[name] });
+    else if (a[name] !== b[name]) out.push({ name: name, change: 'changed', from: a[name], to: b[name] });
+  }
+  return out.sort((x, y) => x.name.localeCompare(y.name));
+}
+
+/**
+ * What changed between two snapshots, by part of the app, and which checks
+ * that calls for. With no earlier snapshot there is nothing to compare, and
+ * that is said - it is not reported as "everything changed".
+ */
+function compare(before, after) {
+  if (!before) return { first: true, files: [], parts: [], checks: [], dependencies: [] };
+  const files = [];
+  const a = before.files || {};
+  const b = after.files || {};
+  for (const rel of Object.keys(b)) {
+    if (!a[rel]) files.push({ path: rel, state: 'added' });
+    else if (a[rel].hash !== b[rel].hash) files.push({ path: rel, state: 'modified' });
+  }
+  for (const rel of Object.keys(a)) if (!b[rel]) files.push({ path: rel, state: 'deleted' });
+  files.sort((x, y) => x.path.localeCompare(y.path));
+  for (const f of files) f.part = partOf(f.path);
+
+  const parts = [];
+  for (const f of files) if (!parts.includes(f.part)) parts.push(f.part);
+  const checks = [];
+  for (const part of parts) for (const id of CHECKS_FOR[part] || []) if (!checks.includes(id)) checks.push(id);
+  return {
+    first: false,
+    files: files,
+    parts: parts,
+    checks: checks,
+    dependencies: dependencyChanges(before, after),
+  };
+}
+
+/**
+ * Findings that were not there last time. Keyed by what they are about rather
+ * than by line number: a line added above a known finding moves it, and a
+ * moved finding reported as new would teach a person to ignore this list.
+ */
+//
+// The detail is part of what a finding is only for the code read, where it is
+// the expression itself. For a recorded flow or a database finding it is the
+// account of how it broke this time - "ended up somewhere different", "could
+// not be opened" - and a flow that is still broken in a new way is the same
+// finding, not a fixed one and a new one.
+function findingKey(f) {
+  return [
+    f.check || '',
+    f.where ? String(f.where).replace(/:\d+$/, '') : '',
+    f.headline ? String(f.headline).replace(/:\d+\b/g, '') : '',
+    f.check === 'frontend' ? f.detail || '' : '',
+  ].join('|');
+}
+
+/** A short, stable name for a finding: what a person types to re-check it. */
+function findingId(f) {
+  return crypto.createHash('sha1').update(findingKey(f)).digest('hex').slice(0, 8);
+}
+
+function newFindings(before, after) {
+  const seen = new Set((before || []).map(findingKey));
+  return (after || []).filter((f) => !seen.has(findingKey(f)));
+}
+
+function goneFindings(before, after) {
+  const now = new Set((after || []).map(findingKey));
+  return (before || []).filter((f) => !now.has(findingKey(f)));
+}
+
+module.exports = {
+  PARTS: PARTS,
+  CHECKS_FOR: CHECKS_FOR,
+  partOf: partOf,
+  listFiles: listFiles,
+  takeSnapshot: takeSnapshot,
+  compare: compare,
+  dependencyChanges: dependencyChanges,
+  findingKey: findingKey,
+  findingId: findingId,
+  newFindings: newFindings,
+  goneFindings: goneFindings,
+};