kryptheon 0.1.20 → 0.1.21

package/kryptheon-look.js

@@ -0,0 +1,259 @@
+// One look at a project: what changed since the last look, which checks that
+// calls for, run the ones that can run, and what is new, fixed or merely
+// deleted. Shared by `npx kryptheon verify` and the dashboard's own watch, so
+// the command and the page can never tell two different stories.
+//
+// Printing is not done here; the caller decides how to say it.
+
+const fs = require('fs');
+const path = require('path');
+const store = require('./kryptheon-store.js');
+const changes = require('./kryptheon-changes.js');
+const dash = require('./kryptheon-dashboard.js');
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Looks once. `runners` does the work that needs the caller's tools:
+ *   runners.frontend()   -> { ran, why }          (the code read)
+ *   runners.regression() -> exit code, or null     (replaying the recordings)
+ * `options.replay` false keeps the recordings from being replayed - the
+ * dashboard's automatic look does that by default, because a replay while the
+ * app is not running reports every flow broken, and that would be a lie.
+ */
+function look(root, runners, options) {
+  const opts = options || {};
+  const paths = store.pathsFor(root);
+  const previous = readJson(paths.snapshot);
+  const now = changes.takeSnapshot(root, previous);
+  const diff = changes.compare(previous, now);
+  const before = dash.buildState(root);
+  const enabled = dash.readConfig(paths).enabled;
+  const available = new Set(dash.CHECKS.filter((c) => c.available).map((c) => c.id));
+
+  // On a first look, every check that can run, so the next look has
+  // something to compare against. `force` adds checks that must run whatever
+  // changed - a re-check has to run the check that found the problem, even
+  // when the fix was made somewhere that check would not otherwise cover.
+  const wanted = (diff.first ? ['frontend', 'regression', 'data'] : diff.checks).slice();
+  for (const id of opts.force || []) if (!wanted.includes(id)) wanted.push(id);
+  const plan = wanted.map((id) => {
+    if (!available.has(id)) return { id: id, state: 'not available yet' };
+    if (!enabled[id]) return { id: id, state: 'switched off in the dashboard' };
+    if (id === 'data') return { id: id, state: 'needs your database - run npx kryptheon-night' };
+    if (id === 'regression' && !before.recordings) return { id: id, state: 'no recordings yet - npx kryptheon record <url>' };
+    if (id === 'regression' && opts.replay === false) return { id: id, state: 'not replayed automatically - press Run now when your app is running' };
+    return { id: id, state: 'run', run: true };
+  });
+
+  // What changed is said before anything runs: a replay can take a minute,
+  // and the person should not sit through it without knowing why.
+  if (typeof runners.beforeRun === 'function') runners.beforeRun(diff, now);
+
+  let regressionExit = null;
+  for (const step of plan.filter((s) => s.run)) {
+    if (step.id === 'frontend') {
+      const r = runners.frontend();
+      step.state = r.ran ? 'ran' : 'could not run: ' + r.why;
+    } else if (step.id === 'regression') {
+      regressionExit = runners.regression();
+      step.state = regressionExit === 0 ? 'ran - every recording held'
+        : regressionExit === 1 ? 'ran - something broke'
+        : 'could not run (exit ' + regressionExit + ')';
+    }
+  }
+
+  const after = dash.buildState(root);
+  const fresh = changes.newFindings(before.findings, after.findings);
+  const gone = changes.goneFindings(before.findings, after.findings);
+  // A finding whose file was deleted is gone, not fixed - the same rule as a
+  // dropped table in the database check. Kept apart, so deleting the code a
+  // finding points at is never mistaken for making it safe.
+  const fileOf = (f) => path.join(root, String(f.where || '').replace(/:\d+$/, ''));
+  const removed = gone.filter((f) => f.check !== 'data' && !fs.existsSync(fileOf(f)));
+  const fixed = gone.filter((f) => removed.indexOf(f) === -1);
+  const openConfirmed = after.findings.filter((f) => f.status === 'confirmed');
+
+  const event = {
+    at: now.takenAt,
+    by: opts.by || 'verify',
+    first: diff.first,
+    files: diff.files,
+    parts: diff.parts,
+    dependencies: diff.dependencies,
+    checks: plan.map((s) => ({ id: s.id, state: s.state })),
+    newFindings: fresh.length,
+    fixed: fixed.length,
+    goneWithFile: removed.length,
+    openConfirmed: openConfirmed.length,
+  };
+  let saveError = null;
+  try {
+    fs.mkdirSync(paths.dir, { recursive: true });
+    fs.writeFileSync(paths.snapshot, JSON.stringify(now) + '\n', 'utf8');
+    fs.appendFileSync(paths.changes, JSON.stringify(event) + '\n', 'utf8');
+  } catch (err) {
+    saveError = err.message;
+  }
+
+  return {
+    diff: diff,
+    snapshot: now,
+    plan: plan,
+    fresh: fresh,
+    fixed: fixed,
+    removed: removed,
+    openConfirmed: openConfirmed,
+    after: after,
+    regressionExit: regressionExit,
+    event: event,
+    saveError: saveError,
+  };
+}
+
+/**
+ * Whether anything changed since the last look, without looking. Cheap enough
+ * to poll: unchanged files keep their hash without being read. The signature
+ * carries each changed file's content hash, so a file still being written
+ * keeps changing it - which is what tells a pause from the end of a task.
+ */
+function pending(root) {
+  const paths = store.pathsFor(root);
+  const previous = readJson(paths.snapshot);
+  if (!previous) return { changed: false, first: true };
+  const now = changes.takeSnapshot(root, previous);
+  const diff = changes.compare(previous, now);
+  const signature = JSON.stringify(diff.files.map((f) => [f.path, f.state, now.files[f.path] ? now.files[f.path].hash : null]));
+  return { changed: diff.files.length > 0, files: diff.files.length, signature: signature };
+}
+
+/**
+ * Looks by itself whenever the project changes, and waits for the change to
+ * settle first. An AI tool writes a dozen files over half a minute; looking
+ * after the first one would report a half-finished task as broken. So a look
+ * happens once the changed files have stayed the same for `quietMs`.
+ *
+ * Recorded flows are not replayed here unless `replay` is true: an automatic
+ * replay while the app is not running reports every flow broken.
+ */
+function startWatch(root, runners, options) {
+  const opts = options || {};
+  const intervalMs = opts.intervalMs || 2000;
+  const quietMs = opts.quietMs || 4000;
+  let seen = null;
+  let since = 0;
+  let busy = false;
+  const doLook = () => {
+    busy = true;
+    try {
+      const result = look(root, runners, { by: 'watch', replay: opts.replay === true });
+      if (typeof opts.onLook === 'function') opts.onLook(result);
+    } catch (err) {
+      if (typeof opts.onError === 'function') opts.onError(err);
+    } finally {
+      busy = false;
+    }
+  };
+  const tick = () => {
+    if (busy) return;
+    const p = pending(root);
+    // Nothing to compare against yet: this first look is the starting point.
+    if (p.first) return doLook();
+    if (!p.changed) {
+      seen = null;
+      return;
+    }
+    if (p.signature !== seen) {
+      seen = p.signature;
+      since = Date.now();
+      return;
+    }
+    if (Date.now() - since >= quietMs) doLook();
+  };
+  const timer = setInterval(tick, intervalMs);
+  if (timer.unref && opts.unref) timer.unref();
+  // Now, not one interval from now: a change made in the first seconds after
+  // the page opened would otherwise land in the starting point and never be
+  // seen as a change at all.
+  tick();
+  return {
+    tick: tick,
+    stop() {
+      clearInterval(timer);
+    },
+  };
+}
+
+// What a broken flow says when the app itself did not answer - which is not
+// evidence either way about the fix.
+const APP_DID_NOT_ANSWER = /could not be opened|took too long to load|net::ERR|ECONNREFUSED/i;
+
+/**
+ * The second half of the loop: someone says a finding is fixed; prove it.
+ *
+ * The check that found it is run again - always, whatever else changed - and
+ * so is every check the changes since the last look call for, so a fix that
+ * breaks something else is caught in the same step. The verdict:
+ *
+ *   fixed               the check ran, and the finding is not there
+ *   still open          the check ran, and the finding is still there
+ *   gone with its file  the file it pointed at was deleted - not the same as fixed
+ *   could not confirm   the check did not run, or the app did not answer
+ *
+ * A fix is never assumed from a changed file. Every attempt is kept.
+ */
+function recheck(root, runners, id, options) {
+  const paths = store.pathsFor(root);
+  const target = dash.buildState(root).findings.find((f) => f.id === id);
+  if (!target) return { found: false };
+
+  const result = look(root, runners, { by: 'recheck', force: [target.check], replay: true });
+  const own = result.plan.find((s) => s.id === target.check);
+  const still = result.after.findings.find((f) => f.id === id);
+  let verdict;
+  let why = '';
+  if (!own || !/^ran/.test(own.state)) {
+    verdict = 'could not confirm';
+    why = own ? own.state : 'the check that found it did not run';
+  } else if (still && target.check === 'regression' && APP_DID_NOT_ANSWER.test(still.detail || '')) {
+    verdict = 'could not confirm';
+    why = 'your app did not answer while the flow was replayed - start it and re-check';
+  } else if (still) {
+    verdict = 'still open';
+    why = still.detail || '';
+  } else if (result.removed.some((f) => f.id === id)) {
+    verdict = 'gone with its file';
+    why = 'the file it pointed at was deleted, which is not the same as fixing it';
+  } else {
+    verdict = 'fixed';
+  }
+  // Problems that appeared with this fix. The finding itself is never one of
+  // them: it was there before, so it cannot be new.
+  const newProblems = result.fresh.map((f) => ({
+    id: f.id, check: f.check, severity: f.severity, status: f.status, where: f.where, headline: f.headline,
+  }));
+  const attempt = {
+    id: id,
+    at: new Date().toISOString(),
+    check: target.check,
+    where: target.where,
+    headline: target.headline,
+    verdict: verdict,
+    why: why,
+    newProblems: newProblems,
+  };
+  try {
+    fs.appendFileSync(paths.fixes, JSON.stringify(attempt) + '\n', 'utf8');
+  } catch (err) {
+    attempt.saveError = err.message;
+  }
+  return Object.assign({ found: true, target: target, look: result }, attempt);
+}
+
+module.exports = { look: look, pending: pending, startWatch: startWatch, recheck: recheck };

package/kryptheon-store.js

@@ -14,6 +14,11 @@
 //     history.jsonl   was kryptheon-history.jsonl
 //     test-results/   was test-results/ (Playwright's screenshots of a failure)
 //     night-last.json was .kryptheon-last.json (kryptheon-night)
+//     code-findings.json  the last frontend code read (kryptheon code)
+//     config.json     which checks are switched on (the dashboard)
+//     snapshot.json   a hash of each project file, to tell what changed
+//     changes.jsonl   one line per change Kryptheon noticed, and what it ran
+//     fixes.jsonl     every re-check of a finding someone tried to fix, and its verdict
 //
 // Only tests/ - the recordings the person made - stays in the project.
 //
@@ -40,6 +45,11 @@ const FILES = {
   history: 'history.jsonl',
   testResults: 'test-results',
   nightLast: 'night-last.json',
+  codeFindings: 'code-findings.json',
+  config: 'config.json',
+  snapshot: 'snapshot.json',
+  changes: 'changes.jsonl',
+  fixes: 'fixes.jsonl',
 };
 
 // What older versions wrote into the project, and where each one goes now.
@@ -122,6 +132,11 @@ function pathsIn(dir) {
     history: path.join(dir, FILES.history),
     testResults: path.join(dir, FILES.testResults),
     nightLast: path.join(dir, FILES.nightLast),
+    codeFindings: path.join(dir, FILES.codeFindings),
+    config: path.join(dir, FILES.config),
+    snapshot: path.join(dir, FILES.snapshot),
+    changes: path.join(dir, FILES.changes),
+    fixes: path.join(dir, FILES.fixes),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "MIT",
   "type": "commonjs",
@@ -31,7 +31,14 @@
     "kryptheon-cleanup.js",
     "kryptheon-baselines.js",
     "kryptheon-project.js",
-    "kryptheon-store.js"
+    "kryptheon-store.js",
+    "kryptheon-code.js",
+    "kryptheon-dashboard.js",
+    "kryptheon-dashboard.html",
+    "kryptheon-dashboard-page.js",
+    "kryptheon-logo.png",
+    "kryptheon-changes.js",
+    "kryptheon-look.js"
   ],
   "engines": {
     "node": ">=20.6.0"
@@ -40,8 +47,14 @@
     "@playwright/test": "^1.62.1"
   },
   "scripts": {
-    "check": "node kryptheon-store.check.js && node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-heal.check.js && node kryptheon-load.check.js && node kryptheon-package.check.js",
+    "check": "node kryptheon-store.check.js && node kryptheon-code.check.js && node kryptheon-dashboard.check.js && node kryptheon-changes.check.js && node kryptheon-look.check.js && node kryptheon-verify.check.js && node kryptheon-recheck.check.js && node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-heal.check.js && node kryptheon-load.check.js && node kryptheon-package.check.js",
     "check:store": "node kryptheon-store.check.js",
+    "check:code": "node kryptheon-code.check.js",
+    "check:dashboard": "node kryptheon-dashboard.check.js",
+    "check:changes": "node kryptheon-changes.check.js",
+    "check:look": "node kryptheon-look.check.js",
+    "check:verify": "node kryptheon-verify.check.js",
+    "check:recheck": "node kryptheon-recheck.check.js",
     "check:reporter": "node kryptheon-reporter.check.js",
     "check:signature": "node kryptheon-signature.check.js",
     "check:stream": "node kryptheon-signature.stream.check.js",