kryptheon 0.1.10 → 0.1.12

package/bin/kryptheon.js

@@ -17,6 +17,8 @@ const replay = require('../kryptheon-replay.js');
 const selectors = require('../kryptheon-selectors.js');
 const recordings = require('../kryptheon-recordings.js');
 const cleanup = require('../kryptheon-cleanup.js');
+const baselines = require('../kryptheon-baselines.js');
+const project = require('../kryptheon-project.js');
 
 const PACKAGE_DIR = path.join(__dirname, '..');
 const USER_DIR = process.cwd();
@@ -1009,6 +1011,39 @@ async function offerToDropLogout(relativeFile) {
 // corrected on the second attempt becomes a wrong login performed on every
 // run. This takes those out and says what it took, because a tool that edits
 // your recording without telling you is worse than one that leaves the mess.
+// A saved result whose recording is gone, or has been recorded again since,
+// describes a page nothing here visits any more. Left in place it is handed
+// to whichever new recording lands on the same name, which then fails on its
+// first run against a baseline it never created.
+function dropDeadBaselines() {
+  const api = (function () {
+    try {
+      return require(path.join(PACKAGE_DIR, 'kryptheon-fixture.js'));
+    } catch (err) {
+      return null;
+    }
+  })();
+  if (!api) return [];
+
+  let all;
+  try {
+    all = api.readBaselines(api.BASELINE_FILE);
+  } catch (err) {
+    return [];
+  }
+  if (!all || !Object.keys(all).length) return [];
+
+  const result = baselines.pruneBaselines(all, USER_DIR);
+  if (!result.changed) return [];
+  try {
+    fs.writeFileSync(api.BASELINE_FILE, JSON.stringify(result.baselines, null, 2) + String.fromCharCode(10), "utf8");
+  } catch (err) {
+    return [];
+  }
+  for (const line of baselines.pruneLines(result.dropped)) console.log(line);
+  return result.dropped;
+}
+
 function tidyRecording(relativeFile) {
   const source = readSpec(relativeFile);
   if (source === null) return [];
@@ -1490,22 +1525,23 @@ function triageSpecs() {
 
 function check(options) {
   const quiet = !!(options && options.quiet);
+
+  // Before anything else. Recordings and results are read out of whatever
+  // folder this was run in, so being in the wrong one does not fail - it
+  // succeeds, about the wrong project. That is the one outcome worth exiting
+  // non-zero over even though nothing was tested.
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+
   // Deliberately not a failure. An assistant told to run this after every
   // change will read a non-zero exit as "something broke" and start fixing
   // code that is perfectly fine. Nothing has been recorded, so there is
   // nothing to verify and nothing to repair.
   if (!listSpecFiles().length) {
-    console.log('');
-    console.log('  Nothing has been recorded yet, so there is nothing to check.');
-    console.log('');
-    console.log('  This is not a failure, and there is nothing in the code to fix.');
-    console.log('');
-    console.log('  To start, record a flow through the app:');
-    console.log('    npx kryptheon record <url>');
-    console.log('');
-    console.log('  That opens a browser window, so it has to be run by a person in');
-    console.log('  a normal terminal - it cannot be done from an AI assistant.');
-    console.log('');
+    for (const line of project.noRecordingsLines()) console.log(line);
     return 0;
   }
   if (!fixtureResolvesForUser() && specsNeedThePackage()) {
@@ -1522,6 +1558,7 @@ function check(options) {
     return 1;
   }
   keepArtefactsOutOfGit();
+  dropDeadBaselines();
 
   const triage = triageSpecs();
 
@@ -1933,6 +1970,7 @@ module.exports = {
   codegenComplaints: codegenComplaints,
   reportFragileSelectors: reportFragileSelectors,
   tidyRecording: tidyRecording,
+  dropDeadBaselines: dropDeadBaselines,
   reportTidying: reportTidying,
   remove: remove,
   deleteRecording: deleteRecording,

package/kryptheon-baselines.js

@@ -0,0 +1,176 @@
+// Keeping a saved result tied to the recording it came from.
+//
+// A baseline used to be identified by where the recording lived and what it was
+// called. That is not enough. Delete the spec files with `del tests\*.spec.js` -
+// which is what anyone does before the tool has taught them `kryptheon remove` -
+// record the flow again, and the new recording is handed the same name. Same
+// path, same title, same key. It inherits the old recording's saved page and
+// fails on its very first run, against a baseline it never created and could
+// never have matched.
+//
+// The report that came out of that said both of these at once:
+//
+//   This has not passed before.
+//   Headings that are gone: "Transactions"
+//
+// Which cannot both be true. If it has never passed there is no baseline of its
+// own to have changed, so there is nothing to show a difference against.
+//
+// So a saved result now also records a fingerprint of the recording that made
+// it. When the recording is gone, or its steps are not the steps the baseline
+// was taken from, the saved result describes something that no longer exists
+// and is thrown away rather than compared against.
+//
+// Pure data work: no Playwright, no test runner.
+
+const fs = require('fs');
+const path = require('path');
+const replay = require('./kryptheon-replay.js');
+
+/** The spec file half of a baseline key, in one consistent shape. */
+function specOf(key) {
+  return String(key || '').split(' :: ')[0].split('\\').join('/');
+}
+
+function titleOf(key) {
+  const parts = String(key || '').split(' :: ');
+  return parts.length > 1 ? parts.slice(1).join(' :: ') : '';
+}
+
+/** The fingerprint of the recording in a file, or null if it cannot be read. */
+function fingerprintOf(userDir, specPath) {
+  let source;
+  try {
+    source = fs.readFileSync(path.join(userDir, specPath), 'utf8');
+  } catch (e) {
+    return null;
+  }
+  return replay.recordingId(source);
+}
+
+/**
+ * What each saved result is: still current, orphaned, or stale.
+ *
+ * `orphan`  - the recording it belongs to is not there any more.
+ * `stale`   - a recording of that name exists, but it is not the one this was
+ *             taken from. This is the case that cost twenty minutes: the file
+ *             is present, so nothing looks wrong.
+ * `legacy`  - written before fingerprints existed. There is no way to tell
+ *             whether it matches, so it is kept, and a fingerprint is written
+ *             in so the question can be answered next time. Guessing here would
+ *             mean either throwing away a good baseline or, far worse, quietly
+ *             accepting a real regression as the new normal.
+ */
+function classifyBaselines(baselines, userDir) {
+  const all = baselines || {};
+  const verdicts = [];
+
+  for (const key of Object.keys(all)) {
+    const entry = all[key];
+    const spec = specOf(key);
+    if (!entry || typeof entry !== 'object') {
+      verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
+      continue;
+    }
+
+    let exists = false;
+    try {
+      exists = fs.statSync(path.join(userDir, spec)).isFile();
+    } catch (e) {
+      exists = false;
+    }
+    if (!exists) {
+      verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
+      continue;
+    }
+
+    const now = fingerprintOf(userDir, spec);
+    if (!entry.recordingId) {
+      verdicts.push({ key: key, state: 'legacy', spec: spec, title: titleOf(key), fingerprint: now });
+      continue;
+    }
+    if (now && entry.recordingId !== now) {
+      verdicts.push({ key: key, state: 'stale', spec: spec, title: titleOf(key), fingerprint: now });
+      continue;
+    }
+    verdicts.push({ key: key, state: 'current', spec: spec, title: titleOf(key) });
+  }
+
+  return verdicts;
+}
+
+/**
+ * The saved results with the dead ones taken out.
+ *
+ * Returns a new object; nothing is written here. The caller decides whether the
+ * file is worth rewriting, so a check that changes nothing never touches it.
+ */
+function pruneBaselines(baselines, userDir) {
+  const all = baselines || {};
+  const verdicts = classifyBaselines(all, userDir);
+  const kept = {};
+  const dropped = [];
+  let stamped = 0;
+
+  for (const verdict of verdicts) {
+    if (verdict.state === 'orphan' || verdict.state === 'stale') {
+      dropped.push(verdict);
+      continue;
+    }
+    const entry = all[verdict.key];
+    if (verdict.state === 'legacy' && verdict.fingerprint) {
+      // Kept as it is, but tied to this recording from now on.
+      kept[verdict.key] = Object.assign({}, entry, { recordingId: verdict.fingerprint });
+      stamped++;
+      continue;
+    }
+    kept[verdict.key] = entry;
+  }
+
+  return { baselines: kept, dropped: dropped, stamped: stamped, changed: dropped.length > 0 || stamped > 0 };
+}
+
+function plural(n, word) {
+  return n + ' ' + word + (n === 1 ? '' : 's');
+}
+
+/**
+ * One line about what was thrown away, said as a fact rather than a warning.
+ *
+ * Nothing has gone wrong when this happens - a recording was deleted or redone,
+ * which is a normal thing to do. It is said out loud only so that a flow which
+ * suddenly starts from scratch is not a mystery.
+ */
+function pruneLines(dropped) {
+  const list = dropped || [];
+  if (!list.length) return [];
+
+  const orphans = list.filter((d) => d.state === 'orphan');
+  const stale = list.filter((d) => d.state === 'stale');
+  const lines = [];
+
+  if (orphans.length) {
+    lines.push(
+      '  ' + plural(orphans.length, 'old baseline') + ' removed - ' +
+        (orphans.length === 1 ? 'its recording is' : 'their recordings are') + ' no longer here.',
+    );
+  }
+  if (stale.length) {
+    lines.push(
+      '  ' + plural(stale.length, 'old baseline') + ' removed - ' +
+        (stale.length === 1 ? 'its recording has' : 'those recordings have') +
+        ' been recorded again since.',
+    );
+  }
+  lines.push('');
+  return lines;
+}
+
+module.exports = {
+  specOf: specOf,
+  titleOf: titleOf,
+  fingerprintOf: fingerprintOf,
+  classifyBaselines: classifyBaselines,
+  pruneBaselines: pruneBaselines,
+  pruneLines: pruneLines,
+};